comecerodocs
Usage agreements

Create or update a billing agreement

POST
/usage/agreements

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

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Request Body

A billing agreement.

application/json
  1. body
agreement_id?string

Send an existing id to update it. Defaults to a new id.

customer_id*string

Required. 1 to 128 of A-Z a-z 0-9 _ . : -.

subscription_id*string

Required. A subscription of the account, in the same mode.

currency*string

Required. The subscription's currency.

effective_from*string

Required.

Formatdate-time
effective_to?string

Set it to end the agreement.

Formatdate-time
billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"

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 POST 'https://api.comecero.com/api/v1/usage/agreements' \  -H 'Content-Type: application/json' \  -d '{  "agreement_id": "agr_cust_8412",  "customer_id": "cust_8412",  "subscription_id": "1101612345678Su7Kq2ZaB",  "currency": "USD",  "effective_from": "2026-11-10T00:00:00Z"}'
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}

List billing agreements GET

By `agreement_id`. When `has_more` is `true`, ask again with `starting_after` set to the last id. A `limit` outside 1 to 100 is moved into that range. Secret and trusted tokens may call it; a limited token may not (`403`).

Get a billing agreement GET

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