Billing & Subscriptions

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

Authorization: Bearer YOUR_AUTH_TOKEN

Subscribe (checkout)

POST /api/billing/checkout

Start a recurring Stripe subscription. Returns a Stripe Checkout URL.

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

{
  "sessionUrl": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Redirect to sessionUrl to complete payment. After payment, Stripe sends a webhook and the subscription activates automatically. You can hold multiple subscriptions — each is an independent budget pool.

---

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

{
  "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" }
      ]
    }
  ],
  "creditBalance": "25.00",
  "legacySubscriptionKeys": []
}

Field	Description
subscriptions	Array of active recurring subscriptions
subscriptions[].status	active, past_due, canceled
subscriptions[].cancelAtPeriodEnd	If true, cancels at period end
creditBalance	Pay-as-you-go credit balance in USD

---

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

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

Send USDC to the address on Base L2, then verify:

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"

{
  "remaining": "25.00"
}

---

Payment address

GET /api/billing/payment-address

Returns the USDC payment address and chain for direct payments.

{
  "address": "0x...",
  "chain": "base"
}

---

How subscriptions work

• Subscriptions are recurring monthly via Stripe — they auto-renew.
• Cancel anytime — the subscription stays active until the end of the billing period.
• You can hold multiple subscriptions, each with its own key pool and budget.
• When a subscription is canceled and the period ends, its keys are revoked automatically.
• Credit keys are not affected by subscription cancellation.