Billing Checkout - AgenticPencil

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"
  }'

import requests

url = "https://api.agenticpencil.com/v1/billing/checkout"
headers = {
    "Authorization": "Bearer ap_your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "plan": "pro",
    "billing_cycle": "monthly",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

const axios = require('axios');

const response = await axios.post(
  'https://api.agenticpencil.com/v1/billing/checkout',
  {
    plan: 'pro',
    billing_cycle: 'monthly',
    success_url: 'https://yourapp.com/success',
    cancel_url: 'https://yourapp.com/cancel'
  },
  {
    headers: {
      'Authorization': 'Bearer ap_your_api_key_here',
      'Content-Type': 'application/json'
    }
  }
);

{
  "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"
  }
}

{
  "status": "success",
  "data": {
    "checkout_url": "https://checkout.stripe.com/pay/cs_test_1234567890abcdef",
    "session_id": "cs_test_1234567890abcdef",
    "plan_details": {
      "plan_name": "Scale Plan",
      "credits_monthly": 5000,
      "rate_limit": 120,
      "price": {
        "amount": 19900,
        "currency": "USD",
        "formatted": "$199.00"
      },
      "billing_cycle": "annual",
      "discount": {
        "code": "LAUNCH50",
        "discount_amount": 9950,
        "discount_percentage": 50
      }
    },
    "expiry_time": "2024-02-17T18:10:32Z"
  }
}

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

POST

billing

checkout

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"
  }'

import requests

url = "https://api.agenticpencil.com/v1/billing/checkout"
headers = {
    "Authorization": "Bearer ap_your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "plan": "pro",
    "billing_cycle": "monthly",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

const axios = require('axios');

const response = await axios.post(
  'https://api.agenticpencil.com/v1/billing/checkout',
  {
    plan: 'pro',
    billing_cycle: 'monthly',
    success_url: 'https://yourapp.com/success',
    cancel_url: 'https://yourapp.com/cancel'
  },
  {
    headers: {
      'Authorization': 'Bearer ap_your_api_key_here',
      'Content-Type': 'application/json'
    }
  }
);

{
  "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"
  }
}

{
  "status": "success",
  "data": {
    "checkout_url": "https://checkout.stripe.com/pay/cs_test_1234567890abcdef",
    "session_id": "cs_test_1234567890abcdef",
    "plan_details": {
      "plan_name": "Scale Plan",
      "credits_monthly": 5000,
      "rate_limit": 120,
      "price": {
        "amount": 19900,
        "currency": "USD",
        "formatted": "$199.00"
      },
      "billing_cycle": "annual",
      "discount": {
        "code": "LAUNCH50",
        "discount_amount": 9950,
        "discount_percentage": 50
      }
    },
    "expiry_time": "2024-02-17T18:10:32Z"
  }
}

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

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"
  }'

import requests

url = "https://api.agenticpencil.com/v1/billing/checkout"
headers = {
    "Authorization": "Bearer ap_your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "plan": "pro",
    "billing_cycle": "monthly",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

const axios = require('axios');

const response = await axios.post(
  'https://api.agenticpencil.com/v1/billing/checkout',
  {
    plan: 'pro',
    billing_cycle: 'monthly',
    success_url: 'https://yourapp.com/success',
    cancel_url: 'https://yourapp.com/cancel'
  },
  {
    headers: {
      'Authorization': 'Bearer ap_your_api_key_here',
      'Content-Type': 'application/json'
    }
  }
);

Authentication

Request Body

string

required

Target subscription plan: “pro” or “scale”

string

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

string

required

URL to redirect users after successful payment

string

required

URL to redirect users if they cancel checkout

Promotional code for discounts (optional)

object

Additional metadata to attach to the subscription (optional)

Response

string

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

object

Show data object

string

Stripe-hosted checkout URL to redirect users to

string

Checkout session ID for tracking

object

Show plan_details object

string

Human-readable plan name

integer

Monthly credit allocation

integer

Requests per minute limit

object

Show price object

integer

Price in cents

string

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

string

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

string

Confirmed billing cycle

object

Discount information if promo code applied

Show discount object

string

Applied promotional code

integer

Discount amount in cents

number

Percentage discount applied

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"
  }
}

{
  "status": "success",
  "data": {
    "checkout_url": "https://checkout.stripe.com/pay/cs_test_1234567890abcdef",
    "session_id": "cs_test_1234567890abcdef",
    "plan_details": {
      "plan_name": "Scale Plan",
      "credits_monthly": 5000,
      "rate_limit": 120,
      "price": {
        "amount": 19900,
        "currency": "USD",
        "formatted": "$199.00"
      },
      "billing_cycle": "annual",
      "discount": {
        "code": "LAUNCH50",
        "discount_amount": 9950,
        "discount_percentage": 50
      }
    },
    "expiry_time": "2024-02-17T18:10:32Z"
  }
}

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

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>

<!-- https://yourapp.com/cancel -->
<div class="cancel-page">
  <h1>Checkout Cancelled</h1>
  <p>Your subscription was not activated.</p>
  <a href="/pricing">View Pricing Again</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

{
  "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.

​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