Credits and burndown
Sell prepaid credit, add it safely with an idempotency key, read the balance, and see exactly what is used first when usage is billed.
Prepaid credit lets a customer pay up front and use it over time: a 100 USD starter pack, a top-up the customer buys, a credit you give after an outage. Credit is held in a credit entitlement in the agreement's currency, and it is used up (burned down) when usage is billed. You create the credit entitlement with the API, then add credit with the API or in the dashboard.
Burndown order
When a period is billed, each metered entitlement's usage is paid in this order:
- Included allowance. Usage up to the allowance of the rate plan (or the entitlement's
capacity) is free. - Prepaid credit. The price of the usage above the allowance is taken from the credit named in
funding_source_entitlement_id, as far as the balance goes. A credit pays only for periods its dates overlap. - Charge. The rest is put on the invoice, rounded to the currency, and charged with the customer's saved payment method. That is the renewal invoice, or a separate usage invoice when the usage can't go on a renewal. With
overage_policyblock, nothing is charged and the run fails withhard_limit_exceededinstead.
When one credit funds several entitlements, they draw on it in the order they are billed: by the hour each one starts in the period, then by entitlement_id. drawdown_priority does not change this order. Late usage lines draw after the period's own lines.
A worked example
The plan includes 100,000 tokens each month, then charges 0.00002 USD per token. The customer has 5.00 USD of credit and uses 500,000 tokens this month.
| Step | Amount |
|---|---|
| Tokens used | 500,000 |
| Included allowance | 100,000 tokens, free |
| Billable tokens | 400,000 |
| Price: 400,000 × 0.00002 USD | 8.00 USD |
| Taken from credit | 5.00 USD (balance now 0.00) |
| Charged on the renewal invoice | 3.00 USD |
The renewal invoice has one usage line for AI tokens of 3.00 USD, next to the plan's price. The billing run shows the whole working: in its prepared_lines, rated_amount is 8.00, credit_debit is 5.00 and amount is 3.00. If the credit had been 8.00 USD or more, nothing would be charged for usage and no usage line would be added.
Credit is used when a period is billed, not when each event arrives. The usage meter keeps counting at a zero balance, so no usage is ever lost. To act sooner, follow usage so far in your app.
Add credit
See Add prepaid credit.
curl -X POST https://api.comecero.com/api/v1/usage/entitlements/credit_cust_8412/credits \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 100.00,
"idempotency_key": "order_ORD5501_starter_pack",
"description": "Starter pack"
}'{ "entitlement_id": "credit_cust_8412", "added": true, "balance": 100.00 }The answer is 200.
amountis in the agreement's currency: more than 0, at most 1,000,000,000, with at most 6 decimals.idempotency_keyis required: 1 to 100 letters, digits,_,.,:or-. It makes a repeat harmless. Use something that names the reason for the credit, such as the order that paid for it. The same key adds the credit once: sending it again answers"added": falsewith the current balance. The same key with another amount answers409.descriptionis up to 200 characters, for your own records.- Credit can only be added to a
creditentitlement (400otherwise) that has not ended (409).
A good pattern is to sell the credit pack as a normal Comecero product or order, and add the credit when the order is paid, with the order id in the idempotency_key. A retried webhook or job then can never add it twice.
Read the balance
See Get an entitlement's balance.
curl https://api.comecero.com/api/v1/usage/entitlements/credit_cust_8412/balance \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN"{
"object": "entitlement_balance",
"entitlement_id": "credit_cust_8412",
"balance": 92.0,
"entries": 2,
"date_computed": "2026-12-01T00:20:11Z",
"billing_region": "us"
}balance is the credit left. entries counts what was added and used. Before anything is written, balance and entries are 0 and date_computed is null. Pass ?billing_region= for an entitlement outside us: without it, the route answers 404 for one in uk or eu.
Rules that keep balances right
- Never below zero. A balance is never overdrawn, even when several entitlements draw on it in one billing run.
- One agreement only. A credit funds entitlements of its own agreement, never another customer's.
- No race. If the credit is used elsewhere between working out a bill and writing it, the bill waits and finishes after the credit is topped up. It shows as waiting for credit under List bills that need attention.
- Every change is recorded. Each top-up and each drawdown is an entry in the credit's ledger.
In the dashboard
Go to Usage Billing, the Customers tab, and open the customer. The Prepaid credit card shows each credit's balance, with Add credit. A bill that waits for credit shows as Waiting for credit: add credit, then use Bill it again under Billing runs if it does not bill within the hour.
Entitlements
What each customer gets on an agreement. Metered usage on a pinned price version, an included allowance, an overage policy, and prepaid credit balances.
Usage with subscriptions
Sell a plan with a monthly fee and usage on top. How usage follows the subscription through renewals, plan changes, cancellations and failed payments.