How usage is billed
Billing periods, late usage, usage on the renewal invoice, the separate usage invoice, prepaid credit, billing runs, held bills and test mode.
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 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:
summetrics: the total of all events.gaugemetrics: 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
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 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
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_tocame 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 hasbilling_run_idandagreement_idset. 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
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
A credit entitlement 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:
- The usage above the allowance is priced as usual.
- The price is taken from the credit first, as far as it goes.
- 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 withhard_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. A metered entitlement has a balance too: it goes down by the units billed each period.
Billing runs
Each billed period is a billing run. Read an agreement's runs with List an agreement's billing runs, newest first, or one run with Get a 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_idis 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 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
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.
- 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
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 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.
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.
Follow usage
See usage this period so far, the shopper's own usage, the events behind a bill, and webhook alerts when a customer nears their allowance.