Billing & Subscriptions

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

Authorization: Bearer YOUR_AUTH_TOKEN

The 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 $44.20/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 pool subscriptions and the currency your next charge will bill in.

Example

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

Response

{
  "success": true,
  "data": {
    "poolPledges": [
      {
        "id": "pledge_uuid",
        "poolId": "pool_uuid",
        "poolSlug": "frontier",
        "modelName": "Frontier Pool",
        "status": "active",
        "monthlyPrice": "61.00",
        "billingCycle": "month",
        "currentPeriodEnd": "2026-05-23T15:55:16.220Z",
        "cancelAtPeriodEnd": false,
        "createdAt": "2026-04-23T15:55:16.220Z",
        "hasKey": true,
        "hours": [8, 9, 10, 11, 12, 13, 14, 15]
      }
    ],
    "chargeCurrency": "usd",
    "eurPriceFactor": 1.0,
    "status": "active",
    "stripeCustomerId": "cus_xxx"
  }
}

Field	Description
`poolPledges`	Array of active pool (Unlimited) subscriptions
`poolPledges[].poolSlug`	Pool identifier — use with `GET /api/pools/:slug` or `GET /api/pools/:slug/my-pledge`
`poolPledges[].status`	`active`, `pending_key`, `past_due`, or `canceled`
`poolPledges[].billingCycle`	`month` or `year`
`poolPledges[].currentPeriodEnd`	End of the current paid period (ISO 8601)
`poolPledges[].hasKey`	Whether the API key has been created for this pledge
`poolPledges[].hours`	Reserved hours of the day (UTC, 0–23) covered by this pledge
`chargeCurrency`	Currency your next charge will bill in — `usd` or `eur` (eurozone cards bill EUR)
`eurPriceFactor`	EUR amount = USD amount × this factor (`1.0` = same number)
`status`	Overall billing status (`active` or `inactive`)
`stripeCustomerId`	Stripe customer ID (null if no card set up)

Cancel subscription

POST /api/billing/cancel-pool/:pledgeId

Cancels a pool subscription. It stays active until the current billing period ends. The pledgeId is the poolPledges[].id from /status.

Example

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

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 history.

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

How subscriptions work

Card subscriptions (Stripe) auto-renew each cycle until you cancel. USDC and x402 subscriptions are one-time — they last 30 days with no auto-renewal, so you renew manually.
Cancel anytime — the subscription stays active until the end of the paid 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.