Entitlements
What each customer gets on an agreement. Metered usage on a pinned price version, an included allowance, an overage policy, and prepaid credit balances.
An entitlement says what one customer gets on their billing agreement. 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
See Create or update an entitlement.
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. |
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
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 | 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 and the usage:threshold_reached webhook, which fires at 50%, 80% and 100% of the allowance.
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.
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, and read what is left with Get an entitlement's balance. A credit can fund only entitlements of its own agreement, so two customers can never share one balance. See Credits and burndown.
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
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 newrate_plan_versionthat 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_idorrate_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.
- 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
| Route | What it answers |
|---|---|
GET /api/v1/usage/agreements/{agreement_id}/entitlements | Every entitlement of the agreement, in any status, sorted by drawdown_priority, then id. |
GET /api/v1/usage/entitlements/{entitlement_id} | One entitlement. |
GET /api/v1/usage/entitlements/{entitlement_id}/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 | Used, included, percent and amount so far for each metered entitlement this period. |
Metrics and aggregations
Define what you count, how events add up for a billing period with sum or gauge, and which properties your usage events may carry.
Credits and burndown
Sell prepaid credit, add it safely with an idempotency key, read the balance, and see exactly what is used first when usage is billed.