Create or update an entitlement
A metered entitlement bills a metric on a pinned rate plan version. A credit entitlement holds prepaid credit for the agreement. Send an existing entitlement_id to update it: its kind, agreement, metric and customer_id can not change. It answers 201 for a create and for an update. Create a credit entitlement before a metered one that draws on it. Secret and trusted tokens may call it; a limited token may not (403).
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
An entitlement.
application/json- body
entitlement_id?stringSend an existing id to update it. Defaults to a new id.
kind?stringDefaults to metered.
"metered""credit"billing_agreement_id*stringRequired.
metric_id?stringMetered: required. Credit: leave out.
rate_plan_id?stringMetered: required. Credit: leave out.
rate_plan_version?integerMetered: required.
funding_source_entitlement_id?stringMetered only. A credit entitlement of the same agreement.
overage_policy?stringallow (the default) charges usage above what credit pays. block makes the billing run fail with hard_limit_exceeded when anything would be charged after credit.
"allow""block"drawdown_priority?integerDefault 0. Only sets the order entitlements are listed in.
capacity?numberUnits included when the rate plan has none.
effective_from?stringDefaults to the agreement's start (metered) or now (credit).
date-timeeffective_to?stringSet it to end the entitlement.
date-timestatus?stringactive (the default) or ended.
"active""ended"billing_region?stringBilling region. Defaults to us.
"us""uk""eu"customer_id?stringOptional. Your id for the customer, 1 to 128 of A-Z a-z 0-9 _ . : -. Billing always uses the agreement's customer_id.
Success.
application/json- response
A metered entitlement bills a metric on a pinned rate plan version. A credit entitlement holds prepaid credit. See https://docs.comecero.com/docs/usage-billing/entitlements
object?stringAlways entitlement_grant.
entitlement_id?stringYour id, or ent_ plus 32 characters.
kind?stringDefaults to metered. Never changes.
"metered""credit"billing_agreement_id?stringThe agreement it belongs to.
metric_id?stringMetered only: the metric billed.
rate_plan_id?stringMetered only: the pinned rate plan.
rate_plan_version?integerMetered only: the pinned version.
funding_source_entitlement_id?stringMetered only: a credit entitlement of the same agreement that pays first.
overage_policy?stringallow charges usage past the allowance and credit. block charges nothing and stops the run with hard_limit_exceeded.
"allow""block"drawdown_priority?integerLower draws on a shared credit first. Default 0.
capacity?|Units included each period when the rate plan has no included_allowance.
status?stringactive, or any other value once ended.
effective_from?stringWhen it starts.
date-timeeffective_to?|When it stops.
date-timecustomer_id?stringThe agreement's customer id.
billing_region?stringBilling region. Defaults to us.
"us""uk""eu"test?booleanTest or live.
curl -X POST 'https://api.comecero.com/api/v1/usage/entitlements' \ -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_standard", "rate_plan_version": 1, "funding_source_entitlement_id": "credit_cust_8412", "overage_policy": "allow"}'{ "object": "entitlement_grant", "entitlement_id": "ent_cust_8412_ai_tokens", "kind": "metered", "billing_agreement_id": "agr_cust_8412", "metric_id": "met_ai_tokens", "rate_plan_id": "ai_tokens_standard", "rate_plan_version": 1, "funding_source_entitlement_id": "credit_cust_8412", "overage_policy": "allow", "drawdown_priority": 0, "capacity": null, "status": "active", "effective_from": "2026-11-01T00:00:00Z", "effective_to": null, "customer_id": "cust_8412", "billing_region": "us", "test": false}