# Entitlements (/docs/usage-billing/entitlements)

An **entitlement** says what one customer gets on their [billing agreement](/docs/usage-billing/set-up#3-link-a-subscription). There are two kinds:

| `kind` | What it gives | Billed as usage |
| --- | --- | --- |
| `metered` (the default) | One metric, priced with one pinned rate plan version, with its included allowance and an overage policy. | Yes |
| `credit` | A prepaid balance in the agreement's currency, which metered entitlements of the same agreement draw on. | No |

A customer on a "Pro" plan might have three entitlements: AI tokens with 1,000,000 included each month, seats billed at their monthly peak, and a $100 credit they bought up front.

## Metered entitlements [#metered-entitlements]

See [Create or update an entitlement](/api/usage-entitlements/save-usage-entitlement).

````bash
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_pro",
    "rate_plan_version": 1,
    "overage_policy": "allow",
    "funding_source_entitlement_id": "credit_cust_8412"
  }'
````

| Field | What it does |
| --- | --- |
| `billing_agreement_id` | Required. The agreement the entitlement belongs to. |
| `metric_id`, `rate_plan_id`, `rate_plan_version` | Required. The metric billed and the exact price version. The rate plan must price that metric. A saved rate plan version never changes, so the customer's price can't move under them. |
| `capacity` | Units included in each period when the rate plan has no `included_allowance`. Use it to give one customer a different allowance on a shared price. |
| `overage_policy` | What happens to usage above the allowance that prepaid credit does not cover. See below. |
| `funding_source_entitlement_id` | A `credit` entitlement of the same agreement that pays for this usage first. Create the credit entitlement first. See [Credits and burndown](/docs/usage-billing/credits). |
| `drawdown_priority` | Sorts the list of an agreement's entitlements. It does not change billing. |
| `effective_from`, `effective_to` | The hours the entitlement covers. `effective_from` defaults to the agreement's start. |
| `status` | `active` (the default) or `ended`. |

An agreement can have one metered entitlement per metric at any hour. Saving a second one that overlaps answers `409`. The agreement, metric, rate plan and entitlement must use the same `billing_region`.

The route is an upsert: sending an existing `entitlement_id` again updates it, and answers `201` too.

### Included allowance [#included-allowance]

Each billing period starts with the full allowance: the rate plan's `included_allowance`, or the entitlement's `capacity` when the plan has none, or 0. Usage up to the allowance costs nothing. Only the usage above it is priced, tiers included. A short period, such as the first one, still gets the full allowance.

For a `sum` metric, a period has one allowance. When an entitlement is replaced during a period (a price change), the new one gets only what is left of it, and its tiers carry on from the usage before it: the period is priced as one count. Each `gauge` entitlement keeps its own full allowance and tiers.

### Overage policy: soft or hard limits [#overage-policy-soft-or-hard-limits]

| `overage_policy` | Works like | What happens past the allowance and credit |
| --- | --- | --- |
| `allow` (the default) | A soft limit | The rest is priced and charged on the invoice: the renewal invoice, or a separate usage invoice when it can't go on a renewal. |
| `block` | A hard limit | Nothing is charged. The billing run fails with `hard_limit_exceeded`, and the agreement's later periods wait. Add credit, then bill it again from the dashboard (**Bill it again**). |

The usage meter keeps counting events either way, so you always have the real usage. To stop a customer from using more in your app before they reach a limit, follow their usage with [usage so far](/docs/usage-billing/follow-usage#this-period-so-far) and the [`usage:threshold_reached`](/docs/usage-billing/follow-usage#usage-alerts) webhook, which fires at 50%, 80% and 100% of the allowance.

## Credit entitlements [#credit-entitlements]

A credit entitlement holds money, not units, in the agreement's currency. It has no metric, rate plan or `funding_source_entitlement_id`. Its `effective_from` defaults to the current hour, and it pays only for periods its dates overlap.

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

Add money to it with [Add prepaid credit](/api/usage-entitlements/add-entitlement-credit), and read what is left with [Get an entitlement's balance](/api/usage-entitlements/get-entitlement-balance). A credit can fund only entitlements of its own agreement, so two customers can never share one balance. See [Credits and burndown](/docs/usage-billing/credits).

Credit entitlements are created with the API only. Once one exists, the dashboard shows it on the customer's page, under **Prepaid credit**, with **Add credit**.

## Changing what a customer gets [#changing-what-a-customer-gets]

Entitlements are dated, so a change never rewrites a period that was already billed.

- **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. Usage before the hour is billed at the old price, usage after it at the new one.
- **New price for everything not billed yet:** send the same entitlement again with the new `rate_plan_id` or `rate_plan_version`. This is what **Change price** does in the dashboard. Usage already billed keeps its price.
- **Upgrade or downgrade of the plan:** do the same for each metric, or end the billing agreement and start a new one at the same hour. See [Usage with subscriptions](/docs/usage-billing/subscriptions#plan-changes).
- **Remove a metric:** send the entitlement 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.
- **Never back in time:** a metered entitlement can't start before the last hour already billed.

An entitlement's `kind`, `billing_agreement_id`, `metric_id` and `customer_id` never change. To move one, end it and create a new one.

## Reading entitlements [#reading-entitlements]

| Route | What it answers |
| --- | --- |
| [`GET /api/v1/usage/agreements/{agreement_id}/entitlements`](/api/usage-agreements/list-agreement-entitlements) | Every entitlement of the agreement, in any status, sorted by `drawdown_priority`, then id. |
| [`GET /api/v1/usage/entitlements/{entitlement_id}`](/api/usage-entitlements/get-usage-entitlement) | One entitlement. |
| [`GET /api/v1/usage/entitlements/{entitlement_id}/balance`](/api/usage-entitlements/get-entitlement-balance) | A credit's balance left. For a metered entitlement, a running total that goes down by the units billed each period. Pass `?billing_region=` for an entitlement outside `us`. |
| [`GET /api/v1/usage/agreements/{agreement_id}/current`](/api/usage-agreements/get-usage-so-far) | Used, included, percent and amount so far for each metered entitlement this period. |
