The customer and spend model

Why customers are a primitive

Most LLM APIs give you one account with one balance behind one rate limit. If you resell that capacity to your own users you end up rebuilding per-user budgets, per-user metering and per-user billing on your side, usually badly. Ringside pushes that down into the platform. A customer is a real object with a stable id (cus_ followed by 24 hex chars), addressable by your own id, and every metered call can be attributed to one.

Two ledgers exist, and keeping them straight is the whole mental model. There is your developer wallet (the single pre-funded pot you top up, shared across Fight Club, Knockout and Ringside). And there is each customer's own ledger, which is independent: a monthly_budget_usd ceiling and an optional prepaid wallet. The platform always charges your developer wallet for the raw provider cost. The customer ledgers are a layer you opt into on top, for capping and for resale.

Two independent metering models

A customer can carry a monthly budget, a prepaid wallet, both or neither. They are orthogonal and enforced at different points. Pick by how you want to treat overspend.

Monthly budget (soft cap)

Set monthly_budget_usd to a non-negative number. Before each attributed call the platform sums that customer's spend for the current calendar month and, if it has already reached the ceiling, refuses with 402 customer_budget_exceeded and fires the customer.budget_exceeded webhook. It is a soft cap in the sense that your developer wallet still has money: you are choosing to stop spending on this one customer, not because you are out of credit. The check is greater-than-or-equal against accumulated spend, so a single call can overshoot the ceiling slightly before the next one is blocked.

Prepaid wallet (hard cap)

A customer wallet is a true prepaid balance. It starts disabled (NULL) and turns on the first time you POST /v1/customers/{id}/wallet/topup. Top-ups must be positive. wallet/adjust applies an arbitrary signed correction (credit or debit) for manual reconciliation. Every mutation writes both the new balance and a ledger row in one transaction, so the balance and history can never drift apart.

The wallet is only debited when you have resale billing configured (a billable header override or a customer billable default, covered below). When it is in play, the pre-call check estimates the billable cost of this request the same way the post-call charge computes it. If the balance is at or below zero you get 402 customer_wallet_empty. If the balance is positive but below the estimate you get 402 customer_wallet_insufficient. Both are 402s; branch on code, never the message.

How customer spend relates to your developer wallet

  incoming metered call (FC-Customer: cus_42)
             |
   [1] customer monthly budget?   --over--> 402 customer_budget_exceeded
             | ok
   [2] customer rate limits?      --over--> 429 customer_rate_limit_exceeded
             | ok
   [3] customer wallet (if resale billing on)
         <= 0  --> 402 customer_wallet_empty
         < est --> 402 customer_wallet_insufficient
             | ok
   [4] run provider call -> raw cost
             |
   [5] DEBIT developer wallet (raw * markup)  --empty--> 402 wallet_empty
             |
   [6] DEBIT customer wallet (billable amount) -- only if resale billing on

Read the running state off two response headers on every metered call: X-Ringside-Wallet-Balance reports the balance after the call and X-Ringside-Wallet-Deducted reports the exact charge. When the call is attributed to a customer that carries a wallet, those headers describe the customer wallet; otherwise they describe your developer pool.

Billable vs raw cost

Raw cost is what the upstream provider charged, after Ringside's platform markup, debited from your developer wallet. Billable is what you want to charge your customer for the same call. They are tracked separately so your margin is just billable minus raw. You control billable in two ways, and they compose: a per-customer default and a per-call header override.

Per-customer defaults (mutually exclusive)

default_billable_markup_pct

A percentage added to the charged cost. 20 means bill the customer 120% of what the call cost you. Must be >= 0.

default_billable_amount_usd

A flat per-call amount, independent of the actual cost. Must be >= 0.

Worked example

Say a call costs you $0.004 after platform markup (the amount debited from your developer wallet). The customer has default_billable_markup_pct: 20. The billable amount is 0.004 * (1 + 20/100) = $0.0048. Your margin on that call is 0.0048 - 0.004 = $0.0008. If instead the customer had default_billable_amount_usd: 0.01, the billable would be a flat $0.01 no matter what the call actually cost.

Read accumulated margin for a customer via GET /v1/customers/{id}/margin, which returns billable totals against raw cost. Markup is applied to the charged cost, so the resolution is costCharged * (1 + pct / 100). The flat amount ignores cost entirely.

The X-FC-Billable-Amount override

When a single call needs a billable amount that the customer default cannot express (per-feature pricing, a promo, a free call) send the X-FC-Billable-Amount request header. The value is a USD amount (a decimal string like 0.008) and must be a non-negative number. Anything else returns 400 invalid_billable_amount. The header wins over any customer default for that one call. When the header is absent the platform falls back to the customer's markup or flat amount, and if neither is set the billable equals the charged cost.

curl https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "FC-Customer: cus_42" \
  -H "X-FC-Billable-Amount: 0.008" \
  -H "Content-Type: application/json" \
  -d '{"model":"fc:openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

# X-FC-Billable-Amount is a USD amount: 0.008 = $0.008 billed to cus_42,
# regardless of this customer's default_billable_markup_pct / amount.

Attribution with FC-Customer

Attach a metered call to a customer with the FC-Customer request header. It accepts three forms and resolution tries them in order.

Resolution is scoped to your developer account at every step, so one developer can never attribute a call to another's customer. A value that starts with cus_ is looked up by id first; the external_id path is tried next and matches active customers only. The OpenAI-compat user body field is also accepted as an attribution source, which is what lets an unmodified OpenAI SDK call still land against a customer.

Lazy-create and FC-Customer-Strict

By default, attributing a call to an unknown external id creates the customer on the fly using your account's billable defaults, then attributes the call to it. That is convenient when your user ids already exist on your side and you would rather not pre-register every one. Lazy-create is rate limited per developer at 100 per hour and 1000 per day. Breaching either returns 429 lazy_create_rate_exceeded.

Turn lazy-create off when you want attribution to fail loudly on a typo or an unprovisioned id. Send FC-Customer-Strict: true (or 1) on the call, or set the account-level default. In strict mode an unresolved id raises 404 customer_not_found instead of silently minting a customer. The per-request header overrides the account default in both directions: FC-Customer-Strict: false re-enables lazy-create for one call even when your account default disables it.

# Without strict: "tenant_99" auto-creates a new cus_ and bills it.
# With strict: an unknown id is a hard 404, so typos do not silently bill.
curl https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "FC-Customer: tenant_99" \
  -H "FC-Customer-Strict: true" \
  -H "Content-Type: application/json" \
  -d '{"model":"fc:openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

# -> 404 { "error": { "type": "not_found_error", "code": "customer_not_found", ... } }

Addressing customers by your own id

You never have to persist our cus_ id. If you set external_id on create, the ext:<external_id> prefix addresses that customer on every customer route, not just the base object. So GET /v1/customers/ext:tenant_42, GET /v1/customers/ext:tenant_42/wallet, .../usage, .../margin, .../client_tokens and .../conversations all resolve the same row. The ext: lookup deliberately resolves to the active row newest-first, so after an archive-and-recreate cycle on the same external_id you always land on the live customer rather than the tombstone.

Lifecycle and status

A customer is either active or archived. Archiving is the normal soft delete (DELETE /v1/customers/{id} or PATCH with status: archived); the row stays, spend history stays, and it stops resolving on the ext: / external_id attribution paths. Creating a customer with an external_id that already belongs to an archived row mints a fresh active row (the archived one is tombstoned), so the external_id is reusable.

A separate GDPR hard delete exists beyond archive. It purges the customer row, anonymizes its usage events (nulls the customer link and strips request/response previews while preserving billing totals) and fires customer.hard_deleted. Archive for normal lifecycle; hard delete only for a data-erasure request.

Every customer-related error code

Hard limits and defaults

• ·Customer id format: cus_ followed by 24 hex characters.
• ·Customer metadata: up to 4 KB serialized; 16 keys max, key <= 64 chars, value <= 512 chars.
• ·monthly_budget_usd, default_billable_markup_pct, default_billable_amount_usd: all must be >= 0.
• ·Billable defaults are mutually exclusive (markup XOR flat amount).
• ·Lazy-create rate limit: 100 new customers per hour and 1000 per day, per developer.
• ·X-FC-Billable-Amount is a USD amount (0.008 = $0.008) and must be a non-negative number.
• ·List pages default to 20 rows, max 100; paginate with after set to the previous next_cursor. Filters: status, external_id, order_by (created_asc | created_desc | last_active_desc).

Related