# How usage is billed (/docs/usage-billing/how-usage-is-billed)

Comecero bills usage at each renewal, and an hourly usage billing job bills what a renewal could not. All times are in UTC, and usage is counted in whole UTC hours. You never start billing yourself.

## Billing periods [#billing-periods]

Billing periods follow the subscription's renewals. Each agreement's first period starts at the hour of its `effective_from`. A period ends at the first of:

- the subscription's next renewal,
- the subscription ending (cancelled or completed),
- the agreement's `effective_to`.

A period that ends at a renewal is usually billed on the renewal invoice, when the renewal is made. Any other period is billed by the hourly job, 15 minutes or more after it has ended. If billing fell behind, the missed periods are billed one at a time, oldest first.

For each period, Comecero takes every metered entitlement that covered part of it, even one that has ended since, and asks the usage meter for that metric's usage for the hours the entitlement covered:

- `sum` metrics: the total of all events.
- `gauge` metrics: the highest hourly peak.

The usage is priced with the rate plan version the entitlement pins. The rate plan's own `effective_from` and `effective_to` play no part. Each period gets the full included allowance, a short first period too. For a `sum` metric, the entitlements of one metric in a period share one allowance. Each `gauge` entitlement keeps its own.

## Late usage [#late-usage]

The usage meter takes events up to 30 days old, so usage can arrive for a period that is already billed. It is not lost. It is billed on the next period's bill, as its own line, for example "AI tokens (token): late usage for 1 Oct 2026 00:00 to 1 Nov 2026 00:00 UTC", priced with the same rate plan version as that period. Only the difference is charged. Invoices that are already made never change, and late usage never lowers a bill.

For periods shorter than a day, late usage is looked for once a day. When an agreement ends, one last pass bills any late usage about 31 days after its last period, and then the agreement's status becomes `ended`.

## Usage on the renewal invoice [#usage-on-the-renewal-invoice]

Usage goes on the subscription's renewal invoice: one invoice each period, with the plan's price for the period ahead and the usage of the period that just ended.

- The usage has one line per metric, for example "AI tokens (token): 1250000 used, 1 Oct 2026 00:00 to 1 Nov 2026 00:00 UTC", plus any late usage lines. Lines of 0 are left out.
- The renewal is never held back or failed because of usage. Usage that reaches the usage meter after the renewal is made is billed as late usage on the next invoice.
- The invoice is paid as one: charged automatically with the customer's saved payment method, after the invoice payment delay in your subscription settings if you set one. If the payment is declined, it is retried as a renewal is. If it is never paid, the subscription is cancelled as usual and the usage on it moves to a separate usage invoice, because it is still owed.
- The agreement's currency must be the subscription's currency.

## The separate usage invoice [#the-separate-usage-invoice]

Usage goes on an invoice of its own when it can't go on a renewal, for example when:

- the period ends without a renewal: the subscription was cancelled or completed, or the agreement's `effective_to` came first,
- the usage meter could not be reached when the renewal was made,
- the meter's count was not complete at the renewal and the price is `tiered_volume` (the only model where more usage can lower the price),
- the run was held for review and Comecero released it,
- the run failed, or waited for prepaid credit, and was billed later,
- a renewal with usage on it was closed unpaid,
- it is the late usage of an agreement that ended.

A separate usage invoice:

- goes to the subscription's customer, in the agreement's currency, with one line per metric (and per late usage line),
- has no `subscription_id`, and has `billing_run_id` and `agreement_id` set. It can't be deleted,
- is charged automatically with the customer's saved payment method, the same way a renewal is. If the customer has no saved payment method that can be charged automatically, it stays open and unpaid,
- is retried on the same schedule as a renewal if the payment is declined. On the first decline the customer is emailed the invoice with a **Pay Invoice Now** link, so they can pay another way,
- never cancels the subscription when its payment fails.

### Minimum invoice [#minimum-invoice]

A separate usage invoice is only made when it comes to at least 1.00 USD, or the same amount in the invoice currency. Smaller amounts are not lost: they wait and join the next invoice. The dashboard shows them under **Waiting for the next invoice**. When an agreement ends, its last invoice is always made, whatever the amount. Usage on a renewal invoice has no minimum.

## Prepaid credit [#prepaid-credit]

A [credit entitlement](/docs/usage-billing/credits) holds a prepaid balance in the agreement's currency. Metered entitlements that name it in `funding_source_entitlement_id` draw on it when their period is billed:

1. The usage above the allowance is priced as usual.
2. The price is taken from the credit first, as far as it goes.
3. The rest is charged on the invoice, rounded to the currency.

A credit pays only for periods its dates overlap. When one credit funds several entitlements, they draw on it in the order they are billed (by the hour each starts in the period, then by `entitlement_id`). Credit is used when a period is billed, not when events arrive: the usage meter keeps counting at a zero balance. What happens past zero depends on the entitlement's `overage_policy`:

- `allow` (the default): the rest is charged.
- `block`: nothing is charged and the billing run fails with `hard_limit_exceeded`.

If the credit is used elsewhere between working out a bill and writing it, the bill waits until the credit is topped up.

Read a credit's balance with [Get an entitlement's balance](/api/usage-entitlements/get-entitlement-balance). A metered entitlement has a balance too: it goes down by the units billed each period.

## Billing runs [#billing-runs]

Each billed period is a billing run. Read an agreement's runs with [List an agreement's billing runs](/api/usage-billing-runs/list-agreement-runs), newest first, or one run with [Get a billing run](/api/usage-billing-runs/get-usage-billing-run). A run's id looks like `billing_run:agr_cust_8412:2026-12-01T00:00:00Z`. Pass `?billing_region=` when reading a run outside `us`: without it, the route answers `404`.

A run's `status` is:

- `pending`: waiting for the usage meter, or being worked on. It is tried again every hour. Comecero is alerted if a run waits more than 24 hours.
- `completed`: billed. `invoice_id` is the invoice the usage is on: the renewal invoice, or a separate usage invoice. It is empty when the amount waited for the minimum or there was nothing to charge.
- `failed`: billing could not go on, and nothing was written or charged. Comecero is alerted. The agreement's later periods wait until this run is billed.

| `failure_code` | Cause | Who fixes it |
| --- | --- | --- |
| `subscription_not_found` | The agreement's subscription is not in your account. | You |
| `invalid_customer_id` | The agreement's `customer_id` is not one the usage meter accepts. | You |
| `missing_metric_or_plan` | An entitlement points to a metric or rate plan version that does not exist. | You |
| `currency_mismatch` | A rate plan's currency is not the agreement's currency. | You |
| `hard_limit_exceeded` | A `block` entitlement needed more than its prepaid credit. | You |
| `missing_credit_entitlement`, `funding_not_a_credit`, `credit_region_mismatch` | The funding entitlement is missing, is not a credit, or is in another billing region. | You |
| `needs_review` | The total is unusually large. See below. | Comecero |

For a cause you can fix, fix it, then go to **Usage Billing**, the **Customers** tab, open the customer, and click **Bill it again** on the run under **Billing runs**. Billing again works only from the dashboard, not with a secret token, and only on the failed run the agreement is waiting on. It makes a new run, and the failed run stays as a record. Any other cause is fixed and billed again by Comecero.

[List bills that need attention](/api/usage-billing-runs/list-usage-attention) lists every run on hold, with `reason` `needs_review`, `failed` or `waiting_for_credit`. The dashboard shows the same under **Needs your attention** on the **Overview** tab.

### Approving a held invoice [#approving-a-held-invoice]

A run fails with `needs_review` when its total is above 5,000 USD (or the same in its currency), or more than 10 times the agreement's last usage bill. The hold is there in case the usage itself is wrong, such as a bug in your app or a leaked usage key. So only Comecero can release it, never your dashboard or an API token.

Nothing is charged until Comecero has checked the usage with you and released it. Meanwhile:

- The held bill shows as **Being checked by Comecero**, also under **Needs your attention** on the **Overview** tab.
- You can check the usage with **See the events** on the run, or with [Read counted usage](/api/usage/get-usage-summary).
- Contact Comecero support with any questions.

Comecero's approval covers the total that was held. If more usage for that period arrived since, the run is held again for the new total. A released run is billed on a separate usage invoice.

## When usage billing is turned off [#when-usage-billing-is-turned-off]

If Comecero turns usage billing off for your account, the billing job and usage alerts skip your agreements, and the `/api/v1/usage` routes answer `403` (except listing and revoking usage keys). Renewals carry no usage. Your usage keys keep working, so usage sent meanwhile is billed once it is turned on again: revoke the keys to stop sending. When it is turned on again, billing carries on from where it stopped.

## Test mode [#test-mode]

Test and live are kept apart. Objects created with a test token are test objects, `apk_test_` usage keys send test usage, and test usage is only billed to test agreements of test subscriptions. Test usage is billed on test invoices, charged with test payment methods. Use test mode to try a whole billing period end to end before you go live.
