# Set up usage billing (/docs/usage-billing/set-up)

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](/docs/usage-billing/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](/docs/basic-concepts/error-handling): the reason is in `error.message`, for example `currency must be a three-letter code`.

## 0. Turn on usage billing [#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 [#1-create-a-metric]

A metric is one thing you count. See [Create a metric](/api/usage-metrics/create-usage-metric).

```bash title="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](/docs/usage-billing/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](/api/usage-metrics/replace-usage-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.

<Callout>
**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**.
</Callout>

## 2. Set a price [#2-set-a-price]

A rate plan prices one metric in one currency. See [Create a rate plan version](/api/usage-rate-plans/create-usage-rate-plan).

```bash title="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_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** |

```json title="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 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.

<Callout>
**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.
</Callout>

## 3. Link a subscription [#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](/api/usage-agreements/save-usage-agreement).

```bash title="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`.

<Callout type="warn">
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](/docs/usage-billing/follow-usage#the-events-behind-a-bill)).
</Callout>

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.

<Callout>
**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.
</Callout>

## 4. Add entitlements [#4-add-entitlements]

### Metered entitlements [#metered-entitlements]

A metered entitlement says "bill this metric on this agreement with this rate plan version". See [Create or update an entitlement](/api/usage-entitlements/save-usage-entitlement).

```bash title="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 [#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.

```bash title="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](/api/usage-entitlements/add-entitlement-credit). The `idempotency_key` makes a repeat harmless: the same key adds the credit once.

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

```json title="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](/docs/usage-billing/credits) for how it is used.

<Callout>
**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.
</Callout>

## 5. Create a usage key [#5-create-a-usage-key]

Your server sends usage with a usage key, not with your API token. See [Create a usage key](/api/usage-keys/create-usage-key).

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

```json title="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..."
}
```

<Callout type="warn">
**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.
</Callout>

- `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](/api/usage-keys/list-usage-keys) (`GET /api/v1/usage/keys`) never shows the full key. [Revoke a usage key](/api/usage-keys/revoke-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.

<Callout>
**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**.
</Callout>

## Next [#next]

[Send usage](/docs/usage-billing/send-usage) from your server.
