comecerodocs
Usage entitlements

Get an entitlement

GET
/usage/entitlements/{entitlement_id}

One entitlement. Secret and trusted tokens may call it; a limited token may not (403).

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

entitlement_id*string

The entitlement id.

Response Body

Success.

application/json
  1. 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?string

Always entitlement_grant.

entitlement_id?string

Your id, or ent_ plus 32 characters.

kind?string

Defaults to metered. Never changes.

Value in"metered""credit"
billing_agreement_id?string

The agreement it belongs to.

metric_id?string

Metered only: the metric billed.

rate_plan_id?string

Metered only: the pinned rate plan.

rate_plan_version?integer

Metered only: the pinned version.

funding_source_entitlement_id?string

Metered only: a credit entitlement of the same agreement that pays first.

overage_policy?string

allow charges usage past the allowance and credit. block charges nothing and stops the run with hard_limit_exceeded.

Value in"allow""block"
drawdown_priority?integer

Lower draws on a shared credit first. Default 0.

capacity?|

Units included each period when the rate plan has no included_allowance.

status?string

active, or any other value once ended.

effective_from?string

When it starts.

Formatdate-time
effective_to?|

When it stops.

Formatdate-time
customer_id?string

The agreement's customer id.

billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"
test?boolean

Test or live.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/usage/entitlements/string'
Example Response
{  "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}

Create or update an entitlement POST

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`).

Get an entitlement's balance GET

For a credit entitlement, the credit left in the agreement's currency. Secret and trusted tokens may call it; a limited token may not (`403`).