Tokens, quotas, LMC and PAYG

Billing in the public API involves three different quantities, and they are regularly confused with one another.

The charge order is always the same and can't be configured: subscription quota first, LMC only for the remainder. If the quota is sufficient, the balance isn't touched at all, and the confirm_payg_topup flag changes nothing.

The 402 fork: the server asks for consent

If the order costs more than the tokens left in the quota, and the service allows pay-as-you-go (Service.payg_access ≠ disabled), the server doesn't create the order and charges nothing; instead it returns 402 with the top-up price. It's not a rejection but a question.

The 402 body:

If you agree, repeat the exact same request with two added fields:

# 1. Regular attempt → HTTP 402 with a quote
curl -s -X POST "$BASE/orders" -H "X-API-KEY: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "<UUID>", "input_text": "…" }'

# 2. Consent: the same body + confirmation and the same quote_token → HTTP 201
curl -s -X POST "$BASE/orders" -H "X-API-KEY: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "<UUID>", "input_text": "…",
        "confirm_payg_topup": true, "quote_token": "q_9f8b2c1a4d3e" }'

If you don't agree, simply don't repeat the request: the order wasn't created, nothing was charged, there's nothing to cancel.

Four confirmation traps

1. The flag alone charges nothing. confirm_payg_topup: true without a quote_token — or with one that has expired, been modified, or was issued for a different order — returns 402 again with a new quote.
2. Consent is an upper bound, not a fixed amount. If the top-up has become cheaper by the time of the charge, the actual price is charged. If it has become more expensive, you get 409 quote_mismatch with the fields actual_lmc_minor and quoted_lmc_minor.
3. Repeating without confirmation is safe and is a standard step: it issues a fresh 402. That's exactly how you refresh a stale or more expensive price — re-sending the old quote_token is pointless.
4. POST /orders/{order}/retry has the same flow — an order retry goes through the same billing and can likewise answer 402 and 409.

Three different branches under code 402

These get confused most often: the code is the same, the reason differs, and the remedies are incompatible.

You can tell insufficient_allowance apart from a top-up offer by the body's contents: the shortfall_*, quote_token and expires_at fields are absent. A confirm_payg_topup sent along with such a request is simply ignored by the server.

Two more domain rejections live nearby, but with code 403: no_subscription and entitlement_missing — there's no subscription, or no required plan feature, at all. And limit_exceeded with code 429 isn't about money but a subscription usage limit; see Limits and the 429 code.

Minor units: why shortfall_lmc_minor can't be shown as is

All monetary fields in the API are integers in the asset's minor units. The real value is calculated as minor / 10 ** precision. In the spec example, shortfall_lmc_minor: 360000000 corresponds to shortfall_lmc: 3.6, which means the divisor here is 10^8, not 100.

Where to check the remainder before ordering

Only live subscriptions are returned (status active, not expired). The remainder is in items[].token_allowance, tokens_used, tokens_remaining. There are no monetary fields here, by design.

GET /usage lists limits: limit_type, limit_value, used, remaining, period_start / period_end / resets_in, plus token_unlimited and is_exceeded. It also shows which services are available to you at all — the set is defined by the subscription's entitlements. For a single service, use GET /usage/{service}, where {service} is the service_code from the GET /usage output (elevenlabs, heygen, lumimg, sfx, music, voice_search), not an arbitrary string.

You can estimate the top-up in advance from the service rate: shortfall_tokens × lumcoin_per_token (the lumcoin_per_token field is also in LMC minor units).

What's visible after the fact, in the order itself

• total_tokens — the full cost in tokens, including retries and regenerations;
• tokens_spent — actually spent (retry repeats aren't charged again);
• tokens_from_quota and tokens_from_payg — the split into the free and paid portions;
• price_units — the locked PAYG amount in minor units, price_formatted — the same amount for display.

Topping up the balance and buying a plan aren't available with an API key — the public surface doesn't process payments. That's done in the dashboard: wallet, plans, account limits.