Set up usage billing
Create a metric, a price, an agreement for a customer's subscription, entitlements and a usage key, with the API or in the dashboard.
You can do most of the setup in the dashboard. Go to Usage Billing in the sidebar: the Overview tab has a checklist (add a metric, set a price, bill a customer for usage, create a usage key, send usage from your app). On a subscription's or customer's page, the Usage billing card has Bill usage. Credit entitlements are set up with the API only. For a walk-through of the screens, see Set up usage billing in the dashboard.
This page walks through the same setup with curl. Every request goes to https://api.comecero.com/api/v1 with a secret token in the Authorization header. Every field and error of each route is in the API reference, linked from each step.
Errors from these routes use the standard error response: the reason is in error.message, for example currency must be a three-letter code.
0. Turn on usage billing
Comecero turns usage billing on for your account. Ask your Comecero contact. Until then the routes on this page answer 403 with error.code usage_billing_off ("Usage billing is not turned on for this account. Ask Comecero to turn it on."). Listing and revoking usage keys still work. Turning it off later keeps everything you set up, and billing carries on when it is turned on again.
1. Create a metric
A metric is one thing you count. See Create a metric.
curl -X POST https://api.comecero.com/api/v1/usage/metrics \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"metric_id": "met_ai_tokens",
"name": "AI tokens",
"event_key": "ai_tokens",
"unit_label": "token",
"aggregation": "sum",
"allowed_properties": ["model"]
}'name(up to 100 characters) andunit_label(up to 96) are required. Both appear on the invoice line, for example "AI tokens (token)".event_keyis themetric_keyyour app sends with each event: 1 to 64 lowercase letters, digits,_,.or-. It must be unique in your account and mode, and it can never change. If you leave it out, thenameis used, which fails when the name has capitals or spaces. So always set it.aggregationis required:sumadds up the quantities of all events. Use it for API calls, tokens, messages, GB-hours.gaugekeeps the highest quantity sent in each hour, and bills the highest hour of the period. Use it for "peak seats" or "peak servers": send the current count at least once an hour.
allowed_propertieslists up to 20 property names your events may carry (1 to 64 letters, digits or_). An event with any other property is rejected.metric_idis optional. Without it you get an id likemet_3f9a....
The answer is the metric, with 201. The usage meter gets a new or changed metric within a few minutes, often at once. Until then, events for it are rejected with unknown_metric. See Metrics and aggregations for how to pick an aggregation.
To change a metric, send the whole definition with PUT /api/v1/usage/metrics/{metric_id} (Create or replace a metric). A field you leave out is reset: allowed_properties to none, status to active. Once the usage meter has the metric, its aggregation can't change (409). Set status to archived to stop taking events for it.
Set it up in the dashboard: Usage Billing, Metrics tab, Add metric. Fill in Name, Metric key, Unit, Counted as (Total (sum) or Highest (gauge)) and Allowed properties.
2. Set a price
A rate plan prices one metric in one currency. See Create a rate plan version.
curl -X POST https://api.comecero.com/api/v1/usage/rate_plans \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"rate_plan_id": "ai_tokens_standard",
"version": 1,
"metric_id": "met_ai_tokens",
"currency": "USD",
"pricing_model": "flat_per_unit",
"included_allowance": 100000,
"overage_price": 0.00002
}'This plan includes 100,000 tokens in each billing period and charges 0.00002 USD for each token after that.
metric_id, currency and pricing_model are required. The plan's currency must be the currency of the agreements that use it. This is not checked when you save an entitlement: a plan in another currency makes the billing run fail with currency_mismatch.
pricing_model | How the price is worked out |
|---|---|
flat_per_unit | Billable units times overage_price (or the first tier's unit_price when there is no overage_price). |
package | Billable units in packages of package_size (1 if not set), rounded up to whole packages, times the price of one package (overage_price, or the first tier's unit_price). With 1,000 units a package at 2.00 USD, 2,500 billable units are 3 packages: 6.00 USD. package_size is only allowed for package. |
tiered_volume | All billable units at the unit_price of the tier the total falls in, plus that tier's flat_fee. |
tiered_graduated | The units in each tier at that tier's unit_price, plus the flat_fee of each tier used. Units past the last tier with an up_to are priced at the last tier's unit_price. |
stair_step | A fixed price for the bracket the total falls in: the flat_fee of that tier, nothing per unit. |
Billable units are the period's usage minus the included allowance. The allowance is the plan's included_allowance, or the entitlement's capacity when the plan has none, or 0. The price, tiers included, applies to billable units only. So tier limits count units above the allowance, not the total.
Each tier is { "up_to": 100000, "unit_price": 0.002, "flat_fee": 5 }. Tiers are required for tiered_volume, tiered_graduated and stair_step, at most 100 of them. up_to is inclusive ("up to 10,000" includes 10,000), above 0 and unique. Set it to null (or leave it out) on the last tier only: one tier at most can be open-ended.
A stair_step plan has a flat_fee on every tier and no unit_price, its last tier is open-ended, and a bigger bracket never costs less than a smaller one. Brackets count billable units, like every tier: a period with no usage above the included allowance costs nothing, and the first bracket's price applies from the first billable unit.
The same 12,000 billable units under each model:
pricing_model | Plan | 12,000 units cost |
|---|---|---|
flat_per_unit | overage_price 0.01 | 12,000 × 0.01 = 120.00 |
package | overage_price 10, package_size 5,000 | 3 packages × 10 = 30.00 |
tiered_graduated | up to 10,000 at 0.01, then 0.005 | 10,000 × 0.01 + 2,000 × 0.005 = 110.00 |
tiered_volume | up to 10,000 at 0.01, then 0.007 | 12,000 × 0.007 = 84.00 |
stair_step | up to 10,000 for 50, up to 50,000 for 150, then 400 | 150.00 |
{
"metric_id": "met_emails",
"currency": "USD",
"pricing_model": "stair_step",
"tiers": [
{ "up_to": 10000, "flat_fee": 50 },
{ "up_to": 50000, "flat_fee": 150 },
{ "up_to": null, "flat_fee": 400 }
]
}Example: a tiered_graduated plan with included_allowance 10,000 and tiers [{ "up_to": 100000, "unit_price": 0.002 }, { "up_to": null, "unit_price": 0.001 }]. With 130,000 used, 120,000 are billable: 100,000 × 0.002 + 20,000 × 0.001 = 220.00 USD.
Limits: prices are at most 1,000,000. Allowances, package sizes and tier limits are at most 1,000,000,000,000. Nothing can be negative.
A period has one allowance for a sum metric. If an entitlement is replaced during a period (a plan change), the new one gets what is left of the allowance, not a new one, and its tiers carry on from the billable units before it: it pays the new plan's price of all the billable units so far, minus its price of the ones before (never less than 0). So a period is one count, as if there had been one plan:
stair_step (up to 10,000 for 50, then 150) | First entitlement | Second entitlement | Period |
|---|---|---|---|
| 3,000, then 3,000 | 50 | 0 | 50, one bracket |
| 8,000, then 3,000 | 50 | 100 | 150, the second bracket |
Units that stay in a bracket the period already reached pay nothing more, even when the new plan's bracket costs more: the bracket counts as paid. Late usage for a split period is billed the same way, as one count: the period's new price less everything already charged for it, never less. On tiered_volume, where more usage can lower every unit's price, no part is ever billed below 0, so a split period can cost more than the same usage under one entitlement.
A gauge metric (seats, a peak) is not added up, so each entitlement keeps its full allowance and starts its tiers at 0. Periods billed before 12 November 2026 started each entitlement's tiers at 0, and their late usage is still priced that way.
On tiered_volume, more usage can lower the price of every unit. If the meter's count for a period is not complete when the subscription renews, that usage waits for the full count and goes on a separate usage invoice instead of the renewal invoice. Every other model, stair_step included, never costs less with more usage: the renewal bills what is counted, and usage that arrives later is billed as the difference on the next invoice (for stair_step, the next bracket's price minus what was billed).
A saved version never changes. Sending the same rate_plan_id and version again answers 409. To change a price, save version 2 and move the customer's entitlement to it (see step 4). An entitlement always pins one exact version. The plan's effective_from and effective_to are stored and sort the list, but billing does not use them.
Set it up in the dashboard: Usage Billing, Prices tab, Add price. Pick the Metric and Currency, choose How it is charged (Per unit, Per package, Tiered, Volume or Stair-step), and fill in Included each billing period and the price, or the table of tiers. Check a bill shows what a period's usage would cost, step by step.
3. Link a subscription
A billing agreement links your own id for a customer to their subscription in Comecero. See Create or update a billing agreement.
curl -X POST https://api.comecero.com/api/v1/usage/agreements \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agreement_id": "agr_cust_8412",
"customer_id": "cust_8412",
"subscription_id": "SB0123456789",
"currency": "USD",
"effective_from": "2026-11-01T00:00:00Z"
}'customer_idis your id for the customer: the same value your app sends asexternal_customer_idin usage events. It is 1 to 128 letters, digits,_,.,:or-. It is not the Comecero customer id. The usage is billed to the subscription's customer.- One
customer_idbelongs to one Comecero customer, and only one agreement for it can cover any hour. subscription_idmust be a subscription of your account, in the same mode (live or test).currencymust be the subscription's currency.effective_fromis required. Billing starts at the start of that hour (UTC). A date in the past is allowed, and the periods already ended are billed at once.statuscan only beactive.
The meter counts events for any external_customer_id. Events for an id with no agreement are counted but never billed. Check a new customer's events in the dashboard (see the events behind a bill).
This route is an upsert. To change an agreement, send it again with the same agreement_id. It answers 201 on an update too. There is no PUT. To end an agreement, send it again with effective_to. When the customer moves to another plan, end agreement A at an hour and start agreement B at the same hour. Once billing has started, effective_from, customer_id and subscription_id can't change, and effective_to can't be before the hours already billed. An agreement also stops billing when its subscription is cancelled or completed.
Set it up in the dashboard: Usage Billing, Customers tab, Bill a customer, or Bill usage on a subscription's page. Choose the subscription (active or in trial), then fill in Your customer id, the Metric and the Price, and pick Start billing usage: From the start of this period or From now. Saving makes the agreement and its metered entitlement together.
4. Add entitlements
Metered entitlements
A metered entitlement says "bill this metric on this agreement with this rate plan version". See Create or update an entitlement.
curl -X POST https://api.comecero.com/api/v1/usage/entitlements \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entitlement_id": "ent_cust_8412_ai_tokens",
"billing_agreement_id": "agr_cust_8412",
"metric_id": "met_ai_tokens",
"rate_plan_id": "ai_tokens_standard",
"rate_plan_version": 1
}'billing_agreement_id,metric_id,rate_plan_idandrate_plan_versionare required.metric_idis the metric's id (not itsevent_key), and the rate plan must price that metric.- The agreement, metric, rate plan and entitlement must use the same
billing_region. effective_fromdefaults to the agreement's. It can't be before the hours already billed.- An agreement can have one metered entitlement per metric for any hour (
409otherwise). overage_policyisallow(the default) orblock. Withblock, usage that prepaid credit does not cover is not charged: the billing run fails withhard_limit_exceeded. Add credit, then bill it again. The usage meter keeps counting either way.- To end an entitlement, send it again with
effective_to, or with"status": "ended"(it then ends at the start of the current hour). It is still billed for the hours it covered.
The route is an upsert by entitlement_id, and answers 201 on an update too. kind, billing_agreement_id, metric_id and customer_id can't change.
To move a customer to a new price from a given hour, end the entitlement at that hour with effective_to, and create a new one for the same metric with the new rate_plan_version that starts at that hour. Sending the same entitlement again with a new rate_plan_id or rate_plan_version instead bills all usage not billed yet at the new price.
Prepaid credit
A credit entitlement holds a prepaid balance in the agreement's currency. It has no metric or rate plan and is never billed as usage. Metered entitlements of the same agreement can draw on it.
curl -X POST https://api.comecero.com/api/v1/usage/entitlements \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entitlement_id": "credit_cust_8412",
"kind": "credit",
"billing_agreement_id": "agr_cust_8412"
}'A credit entitlement must not have metric_id, rate_plan_id or funding_source_entitlement_id. Its effective_from defaults to the current hour. It pays only for periods its dates overlap.
Create the credit first. Then point a metered entitlement at it with "funding_source_entitlement_id": "credit_cust_8412". It must be a credit entitlement of the same agreement (400 otherwise).
Then add credit. See Add prepaid credit. The idempotency_key makes a repeat harmless: the same key adds the credit once.
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": 50.00,
"idempotency_key": "topup-2026-11-01",
"description": "November top-up"
}'{ "entitlement_id": "credit_cust_8412", "added": true, "balance": 50.00 }Sending the same key again answers "added": false with the current balance. The same key with another amount answers 409. Credit can only be added to a credit entitlement (400 otherwise) that has not ended (409). See Credits and burndown for how it is used.
Set it up in the dashboard: Usage Billing, Customers tab, open the customer. What is billed lists the metered entitlements, with Change price and Bill another metric. Prepaid credit shows each credit's balance, with Add credit. Create the credit entitlement itself with the API.
5. Create a usage key
Your server sends usage with a usage key, not with your API token. See Create a usage key.
curl -X POST https://api.comecero.com/api/v1/usage/keys \
-H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Production server" }'{
"object": "usage_key",
"usage_key_id": "uk_5d1c0e7a9b2f4e6c8a0d3b5f7e9c1a2b",
"name": "Production server",
"key_prefix": "apk_live_8Hq2…",
"status": "active",
"active_in_apollo": true,
"test": false,
"date_created": "2026-11-01T09:30:00Z",
"date_revoked": null,
"key": "apk_live_8Hq2..."
}The key is shown once. Only this answer contains the full key. Comecero keeps a hash of it, never the key. Store it in your server's secrets, never in a browser or mobile app.
nameis optional, up to 100 characters.- A key made with a live token starts with
apk_live_and only sends live usage. A test token makesapk_test_keys that only send test usage. active_in_apolloistrueonce the usage meter has the key, usually within seconds and at most a few minutes. Until then the meter answers403.- List usage keys (
GET /api/v1/usage/keys) never shows the full key. Revoke a usage key (POST /api/v1/usage/keys/{usage_key_id}/revoke) is safe to repeat. A revoked key can still send usage for a few minutes, while the revoke reaches the meter. These two routes work even while usage billing is turned off, so a leaked key can always be revoked.
Set it up in the dashboard: Usage Billing, Usage keys tab, Create key. The key is shown once, in Your new usage key. Each key in the list has Revoke.
Next
Send usage from your server.
Set up usage billing in the dashboard
Set up usage billing without code. Add a metric, set a price, bill a customer and create a usage key in the dashboard, then check usage as it arrives.
Send usage
Send usage events from your server to the Comecero usage meter in batches, read the answer for each event, and resend safely without counting twice.