Billing & Subscriptions

All billing endpoints require authentication. Use a Firebase token or management key (mk_):

Authorization: Bearer YOUR_AUTH_TOKEN

POST /api/billing/subscribe

Create a subscription and charge your saved card instantly — no browser redirect. Optionally returns a service key in the same call.

Request body

Parameter	Type	Required	Description
`planSlug`	string	Yes	`standard` or `pro`
`createKey`	boolean	No	If `true`, creates a service key and returns it (default `false`)
`keyName`	string	No	Name for the service key (default `"api-key"`)

Example

curl -X POST https://api.cheapestinference.com/api/billing/subscribe \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"planSlug": "pro", "createKey": true, "keyName": "prod-api"}'

{
  "success": true,
  "data": {
    "subscriptionId": "sub_uuid",
    "stripeSubscriptionId": "sub_1abc...",
    "planSlug": "pro",
    "status": "active",
    "currentPeriodEnd": "2026-04-24T00:00:00.000Z",
    "key": {
      "id": "key_uuid",
      "name": "prod-api",
      "apiKey": "sk_live_abc123..."
    }
  }
}

Requires a saved card on file. You can hold multiple subscriptions — each is an independent budget pool with its own keys.

If key creation fails (e.g. temporary infrastructure issue), the subscription is still created and you’ll get a keyError field with instructions to create the key later via POST /api/keys/subscription.

POST /api/billing/checkout

Start a 30-day subscription via Stripe Checkout. Use this if you don’t have a card on file yet.

Request body

Parameter	Type	Required	Description
`planSlug`	string	Yes	`standard` or `pro`

Example

curl -X POST https://api.cheapestinference.com/api/billing/checkout \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"planSlug": "pro"}'

{
  "success": true,
  "data": {
    "sessionUrl": "https://checkout.stripe.com/c/pay/cs_live_...",
    "sessionId": "cs_live_..."
  }
}

Redirect to sessionUrl to complete payment. After payment, your card is saved and you can use /subscribe for future subscriptions.

Subscription status

GET /api/billing/status

Returns all active subscriptions and credit balance.

Example

curl https://api.cheapestinference.com/api/billing/status \
  -H "Authorization: Bearer mk_your_key"

Response

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "id": "uuid",
        "planSlug": "pro",
        "status": "active",
        "currentPeriodEnd": "2026-03-05T10:00:00.000Z",
        "cancelAtPeriodEnd": false,
        "keyCount": 2,
        "keys": [
          { "id": "key_uuid", "name": "prod-api", "isActive": true, "createdAt": "2026-02-03T10:00:00.000Z" }
        ]
      }
    ],
    "plan": "pro",
    "status": "active",
    "creditBalance": 25.00,
    "stripeCustomerId": "cus_xxx",
    "subscriptionExpiresAt": null,
    "legacySubscriptionKeys": []
  }
}

Field	Description
`subscriptions`	Array of active recurring subscriptions
`subscriptions[].status`	`active`, `past_due`, `canceled`
`subscriptions[].cancelAtPeriodEnd`	If true, cancels at period end
`subscriptions[].keys[]`	Keys with `id`, `name`, `isActive`, `createdAt`
`plan`	Highest active plan slug (`standard` or `pro`)
`status`	Overall billing status (`active` or `inactive`)
`creditBalance`	Pay-as-you-go credit balance in USD (number)
`stripeCustomerId`	Stripe customer ID (null if no card set up)

Cancel subscription

POST /api/billing/cancel

Cancels a specific subscription. It stays active until the current billing period ends.

Request body

Parameter	Type	Required	Description
`subscriptionId`	string	Yes	The subscription UUID from `/status`

Example

curl -X POST https://api.cheapestinference.com/api/billing/cancel \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"subscriptionId": "sub_uuid"}'

Credit top-up

POST /api/billing/topup

Top up your credit balance. Pay with card (Stripe) or USDC on Base.

Request body

Parameter	Type	Required	Description
`amount`	number	Yes	Amount in USD (min $10)
`method`	string	Yes	`stripe`, `stripe_direct`, or `usdc`

Stripe

curl -X POST https://api.cheapestinference.com/api/billing/topup \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "method": "stripe"}'

Returns { "success": true, "data": { "sessionUrl": "...", "sessionId": "..." } } for Stripe Checkout.

USDC

curl -X POST https://api.cheapestinference.com/api/billing/topup \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "method": "usdc"}'

{
  "success": true,
  "data": {
    "address": "0x...",
    "chain": "base",
    "amount": "50"
  }
}

Send USDC to the address on Base L2, then verify (amount must be at least $10):

curl -X POST https://api.cheapestinference.com/api/billing/verify-topup \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"txHash": "0xabc...", "amount": 50}'

Credit balance

GET /api/billing/credits

curl https://api.cheapestinference.com/api/billing/credits \
  -H "Authorization: Bearer mk_your_key"

{
  "success": true,
  "data": {
    "totalTopUp": 100,
    "remaining": 74.50,
    "hasCreditKey": true,
    "creditKeyCount": 2,
    "userId": "ci_user_xxx"
  }
}

Payment address

GET /api/billing/payment-address

Returns the USDC payment address and chain for direct payments.

{
  "success": true,
  "data": {
    "address": "0x...",
    "chain": "base"
  }
}

Payment methods

List saved payment methods

GET /api/billing/payment-methods

curl https://api.cheapestinference.com/api/billing/payment-methods \
  -H "Authorization: Bearer mk_your_key"

{
  "success": true,
  "data": [
    {
      "id": "pm_1abc...",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2028
    }
  ]
}

Remove a payment method

DELETE /api/billing/payment-methods/:id

curl -X DELETE https://api.cheapestinference.com/api/billing/payment-methods/pm_1abc... \
  -H "Authorization: Bearer mk_your_key"

Save a new card (SetupIntent)

POST /api/billing/setup-intent

Returns a Stripe clientSecret to collect card details client-side via Stripe.js.

curl -X POST https://api.cheapestinference.com/api/billing/setup-intent \
  -H "Authorization: Bearer mk_your_key"

{
  "success": true,
  "data": {
    "clientSecret": "seti_1abc_secret_..."
  }
}

Save a new card (hosted)

POST /api/billing/setup-checkout

Returns a Stripe-hosted URL to add a card and billing address.

curl -X POST https://api.cheapestinference.com/api/billing/setup-checkout \
  -H "Authorization: Bearer mk_your_key"

{
  "success": true,
  "data": {
    "sessionUrl": "https://checkout.stripe.com/..."
  }
}

Stripe Customer Portal

POST /api/billing/portal

Opens the Stripe Customer Portal for managing invoices and payment methods.

curl -X POST https://api.cheapestinference.com/api/billing/portal \
  -H "Authorization: Bearer mk_your_key"

{
  "success": true,
  "data": {
    "url": "https://billing.stripe.com/p/session/..."
  }
}

Transaction history

GET /api/billing/transactions

Returns payment and credit history.

curl https://api.cheapestinference.com/api/billing/transactions \
  -H "Authorization: Bearer mk_your_key"

How subscriptions work

Subscriptions last 30 days with no auto-renewal — you renew manually when ready.
Cancel anytime — the subscription stays active until the end of the 30-day period.
You can hold multiple subscriptions, each with its own key pool and budget.
When a subscription expires or is canceled and the period ends, its keys are revoked automatically.
Credit keys are not affected by subscription expiry.

Billing & Subscriptions

Subscribe (direct)

Request body

Example

Subscribe (checkout)

Request body

Example

Subscription status

Example

Response

Cancel subscription

Request body

Example

Credit top-up

Request body

Stripe

USDC

Credit balance

Payment address

Payment methods

List saved payment methods

Remove a payment method

Save a new card (SetupIntent)

Save a new card (hosted)

Stripe Customer Portal

Transaction history

How subscriptions work