Billing Checkout - AgenticPencil

Create a secure checkout session for upgrading to Pro or Scale plans. This endpoint generates a Stripe-hosted checkout URL for seamless subscription management.

curl -X POST "https://api.agenticpencil.com/v1/billing/checkout" \
  -H "Authorization: Bearer ap_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "billing_cycle": "monthly",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
  }'

Authentication

Request Body

plan

string

required

Target subscription plan: “pro” or “scale”

billing_cycle

string

Billing frequency: “monthly” or “annual” (default: “monthly”)

success_url

string

required

URL to redirect users after successful payment

cancel_url

string

required

URL to redirect users if they cancel checkout

Promotional code for discounts (optional)

metadata

object

Additional metadata to attach to the subscription (optional)

Response

status

string

Status of the request (“success” or “error”)

data

object

Show data object

checkout_url

string

Stripe-hosted checkout URL to redirect users to

session_id

string

Checkout session ID for tracking

plan_details

object

Show plan_details object

plan_name

string

Human-readable plan name

credits_monthly

integer

Monthly credit allocation

rate_limit

integer

Requests per minute limit

price

object

Show price object

amount

integer

Price in cents

currency

string

Currency code (e.g., “USD”)

formatted

string

Human-readable price (e.g., “$49.00”)

billing_cycle

string

Confirmed billing cycle

discount

object

Discount information if promo code applied

Show discount object

code

string

Applied promotional code

discount_amount

integer

Discount amount in cents

discount_percentage

number

Percentage discount applied

expiry_time

string

When the checkout session expires (ISO 8601)

{
  "status": "success",
  "data": {
    "checkout_url": "https://checkout.stripe.com/pay/cs_test_1234567890abcdef",
    "session_id": "cs_test_1234567890abcdef",
    "plan_details": {
      "plan_name": "Pro Plan",
      "credits_monthly": 1000,
      "rate_limit": 60,
      "price": {
        "amount": 4900,
        "currency": "USD",
        "formatted": "$49.00"
      },
      "billing_cycle": "monthly"
    },
    "expiry_time": "2024-02-17T18:10:32Z"
  }
}

Credit Cost

Credit Cost: FREE - Creating checkout sessions doesn’t consume credits

This endpoint is free to use and doesn’t affect your credit balance.

Available Plans

Pro Plan

1,000 credits/month
60 requests/minute
$49/month** or **$ 490/year
Priority email support

Scale Plan

5,000 credits/month
120 requests/minute
$199/month** or **$ 1,990/year
Priority support + phone support

Billing Cycles

Monthly Billing

Charged every month on the same date you subscribed
More flexibility to upgrade/downgrade
No long-term commitment
Standard pricing as listed

Annual Billing

Charged once per year
2 months free compared to monthly billing
Better value for consistent usage
Requires annual commitment

Checkout Flow

Create Session

Call this endpoint to generate a secure checkout URL

Redirect User

Send users to the returned checkout_url

User Completes Payment

User enters payment details on Stripe’s secure checkout page

Success/Cancel Handling

User is redirected to your success_url or cancel_url

Webhook Processing

AgenticPencil processes the payment and upgrades the account automatically

Success and Cancel URLs

Your redirect URLs should handle the checkout outcome appropriately:

<!-- https://yourapp.com/success -->
<div class="success-page">
  <h1>Welcome to AgenticPencil Pro!</h1>
  <p>Your account has been upgraded successfully.</p>
  <a href="/dashboard">Go to Dashboard</a>
</div>

Promotional Codes

Percentage Discounts

Apply percentage-based discounts (e.g., “LAUNCH50” for 50% off)

Fixed Amount Discounts

Apply fixed dollar amount discounts (e.g., “SAVE10” for $10 off)

First Month Free

Some codes provide the first billing period at no charge

Extended Trials

Special codes may extend free trial periods

Common Errors

INVALID_PLAN - Unsupported plan type

{
  "status": "error",
  "error": "Invalid plan",
  "message": "Plan must be either 'pro' or 'scale'",
  "code": "INVALID_PLAN"
}

Solution: Use “pro” or “scale” as the plan value

INVALID_URL - Malformed redirect URLs

{
  "status": "error",
  "error": "Invalid URL",
  "message": "success_url must be a valid HTTPS URL",
  "code": "INVALID_URL"
}

Solution: Ensure URLs are valid HTTPS URLs

PROMO_CODE_INVALID - Invalid promotional code

{
  "status": "error",
  "error": "Invalid promo code",
  "message": "The promotional code 'INVALID123' is not valid or has expired",
  "code": "PROMO_CODE_INVALID"
}

Solution: Check the promo code or proceed without it

ALREADY_SUBSCRIBED - User already has active subscription

{
  "status": "error",
  "error": "Already subscribed",
  "message": "User already has an active subscription to this plan",
  "code": "ALREADY_SUBSCRIBED"
}

Solution: User can manage their subscription in the dashboard instead

Best Practices

HTTPS Required: Both success_url and cancel_url must use HTTPS for security.

Session Expiry: Checkout sessions expire after 24 hours. Generate new ones if users need to restart checkout.

User Experience: Clearly explain what users get with each plan before sending them to checkout.

Error Handling: Always handle potential errors gracefully and provide alternative upgrade paths.

Never hardcode promotional codes in your application. Always allow users to input them during checkout or fetch valid codes from your backend.

Endpoints

​Authentication

​Request Body

​Response

​Credit Cost

​Available Plans

Pro Plan

Scale Plan

​Billing Cycles

​Checkout Flow

​Success and Cancel URLs

​Promotional Codes

Percentage Discounts

Fixed Amount Discounts

First Month Free

Extended Trials

​Common Errors

​Best Practices

Authentication

Request Body

Response

Credit Cost

Available Plans

Billing Cycles

Checkout Flow

Success and Cancel URLs

Promotional Codes

Common Errors

Best Practices