comecerodocs
Usage agreements

Get a billing agreement

GET
/usage/agreements/{agreement_id}

One agreement. 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

agreement_id*string

The agreement id.

Response Body

Success.

application/json
  1. response

Links your id for a customer to one of their Comecero subscriptions.

object?string

Always billing_agreement.

agreement_id?string

Your id, or agr_ plus 32 characters.

customer_id?string

Your id for the customer: the external_customer_id in usage events.

subscription_id?string

The Comecero subscription the usage is billed next to.

currency?string

The subscription's currency.

status?string

active, or ended after its last late-usage pass.

Value in"active""ended"
effective_from?string

When billing starts.

Formatdate-time
effective_to?|

When billing stops.

Formatdate-time
billed_through?string

Usage is billed up to this hour.

Formatdate-time
last_billing_run_id?|

The last completed billing run.

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/agreements/string'
Example Response
{  "object": "billing_agreement",  "agreement_id": "agr_cust_8412",  "customer_id": "cust_8412",  "subscription_id": "SB0123456789",  "currency": "USD",  "status": "active",  "effective_from": "2026-11-01T00:00:00Z",  "effective_to": null,  "billed_through": "2026-11-01T00:00:00Z",  "last_billing_run_id": null,  "billing_region": "us",  "test": false}

Create or update a billing agreement POST

Links your id for a customer (the `external_customer_id` your app sends to the usage meter) to one of their Comecero subscriptions, which pays for the usage. Send an existing `agreement_id` to update it, and `effective_to` to end it. It answers `201` for a create and for an update. Only one agreement per customer can cover any hour, and the currency must be the subscription's. Secret and trusted tokens may call it; a limited token may not (`403`).

Get usage this period so far GET

Used, included, percent and amount so far for each metered entitlement, worked out as the next bill will be, before prepaid credit. Kept for 5 minutes, so it can be a few minutes behind. Secret and trusted tokens may call it; a limited token may not (`403`).