comecerodocs
Usage billing

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.

Request
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) and unit_label (up to 96) are required. Both appear on the invoice line, for example "AI tokens (token)".
  • event_key is the metric_key your 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, the name is used, which fails when the name has capitals or spaces. So always set it.
  • aggregation is required:
    • sum adds up the quantities of all events. Use it for API calls, tokens, messages, GB-hours.
    • gauge keeps 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_properties lists up to 20 property names your events may carry (1 to 64 letters, digits or _). An event with any other property is rejected.
  • metric_id is optional. Without it you get an id like met_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.

Request
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_modelHow the price is worked out
flat_per_unitBillable units times overage_price (or the first tier's unit_price when there is no overage_price).
packageBillable 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_volumeAll billable units at the unit_price of the tier the total falls in, plus that tier's flat_fee.
tiered_graduatedThe 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_stepA 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_modelPlan12,000 units cost
flat_per_unitoverage_price 0.0112,000 × 0.01 = 120.00
packageoverage_price 10, package_size 5,0003 packages × 10 = 30.00
tiered_graduatedup to 10,000 at 0.01, then 0.00510,000 × 0.01 + 2,000 × 0.005 = 110.00
tiered_volumeup to 10,000 at 0.01, then 0.00712,000 × 0.007 = 84.00
stair_stepup to 10,000 for 50, up to 50,000 for 150, then 400150.00
A stair_step plan
{
  "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 entitlementSecond entitlementPeriod
3,000, then 3,00050050, one bracket
8,000, then 3,00050100150, 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.

A billing agreement links your own id for a customer to their subscription in Comecero. See Create or update a billing agreement.

Request
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_id is your id for the customer: the same value your app sends as external_customer_id in 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_id belongs to one Comecero customer, and only one agreement for it can cover any hour.
  • subscription_id must be a subscription of your account, in the same mode (live or test).
  • currency must be the subscription's currency.
  • effective_from is 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.
  • status can only be active.

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.

Request
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_id and rate_plan_version are required. metric_id is the metric's id (not its event_key), and the rate plan must price that metric.
  • The agreement, metric, rate plan and entitlement must use the same billing_region.
  • effective_from defaults 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 (409 otherwise).
  • overage_policy is allow (the default) or block. With block, usage that prepaid credit does not cover is not charged: the billing run fails with hard_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.

Request
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.

Request
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"
  }'
Response (200)
{ "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.

Request
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" }'
Response (201)
{
  "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.

  • name is optional, up to 100 characters.
  • A key made with a live token starts with apk_live_ and only sends live usage. A test token makes apk_test_ keys that only send test usage.
  • active_in_apollo is true once the usage meter has the key, usually within seconds and at most a few minutes. Until then the meter answers 403.
  • 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.

On this page