# Credits and burndown (/docs/usage-billing/credits)

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](/docs/usage-billing/entitlements#credit-entitlements) 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 [#burndown-order]

When a period is billed, each metered entitlement's usage is paid in this order:

1. **Included allowance.** Usage up to the allowance of the rate plan (or the entitlement's `capacity`) is free.
2. **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.
3. **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_policy` `block`, nothing is charged and the run fails with `hard_limit_exceeded` instead.

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 [#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.

<Callout>
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](/docs/usage-billing/follow-usage#this-period-so-far) in your app.
</Callout>

## Add credit [#add-credit]

See [Add prepaid credit](/api/usage-entitlements/add-entitlement-credit).

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

````json
{ "entitlement_id": "credit_cust_8412", "added": true, "balance": 100.00 }
````

The answer is `200`.

- `amount` is in the agreement's currency: more than 0, at most 1,000,000,000, with at most 6 decimals.
- `idempotency_key` is 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": false` with the current balance. The same key with another amount answers `409`.
- `description` is up to 200 characters, for your own records.
- Credit can only be added to a `credit` entitlement (`400` otherwise) 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 [#read-the-balance]

See [Get an entitlement's balance](/api/usage-entitlements/get-entitlement-balance).

````bash
curl https://api.comecero.com/api/v1/usage/entitlements/credit_cust_8412/balance \
  -H "Authorization: Bearer $COMECERO_SECRET_TOKEN"
````

````json
{
  "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 [#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](/api/usage-billing-runs/list-usage-attention).
- **Every change is recorded.** Each top-up and each drawdown is an entry in the credit's ledger.

## In the dashboard [#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.
