# Usage billing API (/docs/usage-billing/usage-billing-api)

The usage billing routes are on `https://api.comecero.com/api/v1`. Call them from your server with a [secret token](/docs/basic-concepts/authentication) in the `Authorization: Bearer` header. Limited tokens can not call them, except [Get a customer's usage this period](/api/usage/get-customer-usage), which a shopper's token may call for its own customer.

A test token reads and writes test objects only, and a live token live objects only. Until Comecero turns usage billing on for your account, the routes answer `403` with the code `usage_billing_off`. Listing and revoking usage keys still work then.

Sending usage events is not on this API. Your server sends them to the usage meter with a usage key: see the [Usage meter API](/docs/usage-billing/usage-meter-api).

## Usage metrics [#usage-metrics]

What you count and bill for, such as API calls or AI tokens, and how the events add up.

| Route | Method and path |
| --- | --- |
| [Create a metric](/api/usage-metrics/create-usage-metric) | `POST /usage/metrics` |
| [List metrics](/api/usage-metrics/list-usage-metrics) | `GET /usage/metrics` |
| [Get a metric](/api/usage-metrics/get-usage-metric) | `GET /usage/metrics/{metric_id}` |
| [Create or replace a metric](/api/usage-metrics/replace-usage-metric) | `PUT /usage/metrics/{metric_id}` |

## Usage rate plans [#usage-rate-plans]

The price of a metric: an included allowance, a price per unit, packages or tiers. Each version is fixed once saved.

| Route | Method and path |
| --- | --- |
| [Create a rate plan version](/api/usage-rate-plans/create-usage-rate-plan) | `POST /usage/rate_plans` |
| [List rate plans](/api/usage-rate-plans/list-usage-rate-plans) | `GET /usage/rate_plans` |
| [Get a rate plan version](/api/usage-rate-plans/get-usage-rate-plan) | `GET /usage/rate_plans/{rate_plan_id}/versions/{version}` |

## Usage agreements [#usage-agreements]

Link your own id for a customer to their Comecero subscription, and read their usage so far.

| Route | Method and path |
| --- | --- |
| [Create or update a billing agreement](/api/usage-agreements/save-usage-agreement) | `POST /usage/agreements` |
| [List billing agreements](/api/usage-agreements/list-usage-agreements) | `GET /usage/agreements` |
| [Get a billing agreement](/api/usage-agreements/get-usage-agreement) | `GET /usage/agreements/{agreement_id}` |
| [Get usage this period so far](/api/usage-agreements/get-usage-so-far) | `GET /usage/agreements/{agreement_id}/current` |
| [List an agreement's entitlements](/api/usage-agreements/list-agreement-entitlements) | `GET /usage/agreements/{agreement_id}/entitlements` |
| [Find a customer's subscription](/api/usage-agreements/get-usage-subscription-context) | `GET /usage/subscription_context` |

## Usage entitlements [#usage-entitlements]

Put a metric and price on an agreement, or hold prepaid credit, and read the balance.

| Route | Method and path |
| --- | --- |
| [Create or update an entitlement](/api/usage-entitlements/save-usage-entitlement) | `POST /usage/entitlements` |
| [Get an entitlement](/api/usage-entitlements/get-usage-entitlement) | `GET /usage/entitlements/{entitlement_id}` |
| [Get an entitlement's balance](/api/usage-entitlements/get-entitlement-balance) | `GET /usage/entitlements/{entitlement_id}/balance` |
| [Add prepaid credit](/api/usage-entitlements/add-entitlement-credit) | `POST /usage/entitlements/{entitlement_id}/credits` |

## Usage keys [#usage-keys]

The keys your server uses to send usage events to the usage meter.

| Route | Method and path |
| --- | --- |
| [Create a usage key](/api/usage-keys/create-usage-key) | `POST /usage/keys` |
| [List usage keys](/api/usage-keys/list-usage-keys) | `GET /usage/keys` |
| [Revoke a usage key](/api/usage-keys/revoke-usage-key) | `POST /usage/keys/{usage_key_id}/revoke` |

## Usage billing runs [#usage-billing-runs]

One billed period of one agreement, with the invoice its usage is on.

| Route | Method and path |
| --- | --- |
| [List an agreement's billing runs](/api/usage-billing-runs/list-agreement-runs) | `GET /usage/agreements/{agreement_id}/runs` |
| [List bills that need attention](/api/usage-billing-runs/list-usage-attention) | `GET /usage/attention` |
| [Get a billing run](/api/usage-billing-runs/get-usage-billing-run) | `GET /usage/runs/{billing_run_id}` |

## Usage [#usage]

Read usage totals and the events behind them.

| Route | Method and path |
| --- | --- |
| [Read counted usage](/api/usage/get-usage-summary) | `GET /usage/summary` |
| [List a customer's events](/api/usage/list-usage-events) | `GET /usage/events` |
| [Get a customer's usage this period](/api/usage/get-customer-usage) | `GET /customers/{customer_id}/usage` |

## Webhook [#webhook]

[Usage threshold reached](/api/webhooks/usage-threshold-reached) (`usage:threshold_reached`) fires when a customer passes 50%, 80% or 100% of an included allowance. See [usage alerts](/docs/usage-billing/follow-usage#usage-alerts).
