comecerodocs
Usage billing

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:

kindWhat it givesBilled as usage
metered (the default)One metric, priced with one pinned rate plan version, with its included allowance and an overage policy.Yes
creditA 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"
  }'
FieldWhat it does
billing_agreement_idRequired. The agreement the entitlement belongs to.
metric_id, rate_plan_id, rate_plan_versionRequired. 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.
capacityUnits 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_policyWhat happens to usage above the allowance that prepaid credit does not cover. See below.
funding_source_entitlement_idA credit entitlement of the same agreement that pays for this usage first. Create the credit entitlement first. See Credits and burndown.
drawdown_prioritySorts the list of an agreement's entitlements. It does not change billing.
effective_from, effective_toThe hours the entitlement covers. effective_from defaults to the agreement's start.
statusactive (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_policyWorks likeWhat happens past the allowance and credit
allow (the default)A soft limitThe rest is priced and charged on the invoice: the renewal invoice, or a separate usage invoice when it can't go on a renewal.
blockA hard limitNothing 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 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.
  • 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

RouteWhat it answers
GET /api/v1/usage/agreements/{agreement_id}/entitlementsEvery 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}/balanceA 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}/currentUsed, included, percent and amount so far for each metered entitlement this period.

On this page