# Usage billing and credits (/docs/usage-billing)

Usage billing charges a customer for what they use: API calls, AI tokens, storage, seats, messages, or anything else your app can count. Your app sends usage events to the Comecero usage meter. When the customer's subscription renews, Comecero adds up their usage for the period that just ended, takes off what their plan includes and any prepaid credit, prices the rest and usually puts it on the renewal invoice, next to the plan's price for the period ahead. The invoice is charged with the customer's saved payment method, as every renewal is.

It works with the subscriptions you already sell on Comecero. A customer pays one invoice each billing cycle: the fee for their plan and the usage above what the plan includes.

## What you get [#what-you-get]

| Feature | What it does |
| --- | --- |
| **Usage metering** | Send events from your server in batches of up to 1,000. A resend of the same event is never counted twice. Late events up to 30 days old are still billed. See [Send usage](/docs/usage-billing/send-usage). |
| **Metrics and aggregations** | Define what you count and how it adds up: `sum` (total used) or `gauge` (highest hourly level). See [Metrics and aggregations](/docs/usage-billing/metrics-and-aggregations). |
| **Rate plans** | Price a metric with an included allowance and a price per unit, per package, or in volume or graduated tiers. Each version is fixed once saved. See [Set a price](/docs/usage-billing/set-up#2-set-a-price). |
| **Entitlements** | Put a metric on a customer at a pinned price version, with an overage policy: charge the overage, or stop at a hard limit. See [Entitlements](/docs/usage-billing/entitlements). |
| **Credits and burndown** | Sell prepaid credit. Usage is paid from the included allowance first, then from credit, and only then charged. See [Credits and burndown](/docs/usage-billing/credits). |
| **Subscription billing** | Usage periods follow the subscription's renewals. Each period's usage usually goes on the renewal invoice and is charged with it. See [Usage with subscriptions](/docs/usage-billing/subscriptions). |
| **Safe invoices** | Usage that can't go on a renewal gets a separate usage invoice, and small amounts wait for the next invoice. Unusually large usage is held, and nothing is charged until Comecero has checked it with you. See [How usage is billed](/docs/usage-billing/how-usage-is-billed). |
| **Usage so far and alerts** | Show usage for the current period in your app, on the shopper's account page and in the dashboard. Get a `usage:threshold_reached` webhook at 50%, 80% and 100% of an allowance. See [Follow usage](/docs/usage-billing/follow-usage). |
| **Comecero Express Payments** | When your account sells through Comecero Express Payments, usage is charged through it like every other sale. See [Merchant of record](/docs/usage-billing/subscriptions#merchant-of-record). |

<Callout>
Comecero turns usage billing on for each account. Until it is on, the `/api/v1/usage` routes answer `403` with the error code `usage_billing_off` ("Usage billing is not turned on for this account. Ask Comecero to turn it on."). Only listing and revoking usage keys still work. `GET /api/v1/customers/{customer_id}/usage` answers an empty list instead of an error.
</Callout>

## How it works [#how-it-works]

1. **Your app counts.** Each time a customer uses something, your server sends an event to the usage meter, for example "customer `cust_8412` used 1,250 AI tokens".
2. **The meter adds it up.** Events are counted by customer, metric and UTC hour. A resend of the same event is never counted twice.
3. **Comecero bills each period.** When the customer's subscription renews, Comecero reads the period's usage, takes off the included allowance, prices the rest with the rate plan version the customer is on, then takes the price from prepaid credit.
4. **The customer pays.** What is left goes on the renewal invoice, next to the plan's price, and is charged with the customer's saved payment method.

## How the pieces fit [#how-the-pieces-fit]

| Object | What it is |
| --- | --- |
| Metric | What you count, for example `ai_tokens`. Its `event_key` is the `metric_key` your app sends. It adds events up (`sum`) or keeps the highest hourly reading (`gauge`). |
| Rate plan | The price of a metric, in one currency. Each version is fixed once it is saved. |
| Billing agreement | Links your own id for a customer to one of their Comecero subscriptions. Usage is invoiced to that subscription's customer, in its currency. |
| Entitlement | Puts a metric and a pinned rate plan version on an agreement (`metered`), or holds prepaid credit for the agreement (`credit`). |
| Credit | Money added to a `credit` entitlement. Metered entitlements of the same agreement can draw on it when a period is billed. |
| Usage key | Lets your server send events to the usage meter. Starts with `apk_live_` or `apk_test_`. |
| Usage event | One thing that happened, for example "customer cust_8412 used 1,250 tokens". |
| Billing run | One billed period of one agreement, with the invoice its usage is on. |

Your server never calls the usage meter with a Comecero API token. You set things up with the Comecero API (`https://api.comecero.com/api/v1/usage/...`) and a secret token. You send events to the usage meter (`https://usage.comecero.com/v1/events`) with a usage key.

<Callout type="warn">
The meter counts events for any `external_customer_id`. Usage is billed only when that id is the `customer_id` of a billing agreement. Events for any other id are counted but never billed.
</Callout>

## Before you start [#before-you-start]

- Ask Comecero to turn on usage billing for your account.
- Call the `/api/v1/usage` routes from your server with a [secret token](/docs/basic-concepts/authentication). The dashboard uses a trusted token. Limited (shopper) tokens can't call them. The token needs permission on the resources the routes use: `metrics`, `rate_plans`, `billing_agreements`, `entitlement_grants`, `entitlement_balance_snapshots`, `entitlement_ledger_entries`, `billing_runs` and `usage_keys`.
- Each customer you bill for usage needs a subscription in Comecero. Usage goes on its renewal invoices and uses its currency.
- Test first. A test token makes test objects and `apk_test_` usage keys, and test usage is only billed to test agreements.

## Set it up in the dashboard [#set-it-up-in-the-dashboard]

Go to **Usage Billing** in the sidebar. It has five tabs: **Overview**, **Customers**, **Prices**, **Metrics** and **Usage keys**. The **Overview** tab has a checklist that walks you through the setup: add a metric, set a price, bill a customer for usage, create a usage key, and send usage from your app. Every pricing model (per unit, per package, tiered, volume and stair-step) can be set up there.

[Set up usage billing in the dashboard](/docs/usage-billing/dashboard) walks through every screen, with pictures.

## Steps [#steps]

<Steps>
<Step>

Ask Comecero to turn on usage billing.

</Step>
<Step>

[Create a metric](/docs/usage-billing/set-up#1-create-a-metric) for each thing you count.

</Step>
<Step>

[Create a rate plan](/docs/usage-billing/set-up#2-set-a-price) for each metric.

</Step>
<Step>

[Create a billing agreement](/docs/usage-billing/set-up#3-link-a-subscription) for each customer's subscription.

</Step>
<Step>

[Add entitlements](/docs/usage-billing/set-up#4-add-entitlements) to the agreement, and prepaid credit if you sell it.

</Step>
<Step>

[Create a usage key](/docs/usage-billing/set-up#5-create-a-usage-key) for your server.

</Step>
<Step>

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

</Step>
</Steps>

Want it all in one script? The [Quickstart](/docs/usage-billing/quickstart) does every step in Node.js. Every route is in the API reference, starting with [Create a metric](/api/usage-metrics/create-usage-metric). Sending events is in the [Usage meter API](/docs/usage-billing/usage-meter-api).

## Billing regions [#billing-regions]

Every metric, rate plan, agreement and entitlement has a `billing_region`: `us` (the default), `uk` or `eu`. The objects of one agreement must all use the same region. Reading a billing run or a balance looks in `us` unless you pass `?billing_region=` in the query string, and answers `404` when the region does not match.
