Billing & Subscriptions

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

Authorization: Bearer YOUR_AUTH_TOKEN

Deprecated. The legacy flat plans (Standard, Pro, and their annual variants) have been retired — GET /api/plans returns an empty list and the POST /api/billing/subscribe / POST /api/billing/checkout endpoints below are no longer used for new subscriptions.

The current subscription product is pool time-block subscriptions (“Unlimited Subscriptions”): reserve 1–3 daily 8-hour UTC blocks (asia, europe, americas) for unlimited usage during your reserved hours, from $39/mo. Subscribe via POST /api/pools/:id/subscribe. See the full reference at Unlimited Subscriptions API.

# List available pools
curl https://api.cheapestinference.com/api/pools \
  -H "Authorization: Bearer mk_your_key"

# Subscribe to a time block (e.g. Europe), billed monthly
curl -X POST https://api.cheapestinference.com/api/pools/POOL_SLUG/subscribe \
  -H "Authorization: Bearer mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"blocks": ["europe"], "quantity": 1, "billingCycle": "month"}'

After subscribing, create your API key with POST /api/keys/subscription.

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": [],
    "poolPledges": [
      {
        "id": "pledge_uuid",
        "poolId": "pool_uuid",
        "poolSlug": "kimi26",
        "status": "active",
        "currentPeriodEnd": "2026-05-23T15:55:16.220Z",
        "cancelAtPeriodEnd": true,
        "hasKey": true
      }
    ],
    "plan": null,
    "status": "active",
    "creditBalance": 25.00,
    "stripeCustomerId": "cus_xxx",
    "subscriptionExpiresAt": null,
    "legacySubscriptionKeys": []
  }
}

Field	Description
`subscriptions`	Array of active recurring subscriptions from legacy flat plans. Now always empty — flat plans are retired.
`subscriptions[].status`	`active`, `past_due`, `canceled`
`subscriptions[].cancelAtPeriodEnd`	If true, cancels at period end
`subscriptions[].keys[]`	Keys with `id`, `name`, `isActive`, `createdAt`
`poolPledges`	Array of active pool (Unlimited) subscriptions — the current subscription product
`poolPledges[].poolSlug`	Pool identifier — use with `GET /api/pools/:slug` or `GET /api/pools/:slug/my-pledge`
`poolPledges[].status`	`active`, `pending_key`, `past_due`, `canceled`
`poolPledges[].hasKey`	Whether the API key has been created for this pledge
`plan`	Highest active legacy flat plan slug, or `null` (flat plans are retired)
`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.