comecerodocs
Usage agreements

List billing agreements

GET
/usage/agreements

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

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Query Parameters

customer_id?string

Only this customer's agreements.

subscription_id?string

Only the agreements of this subscription.

starting_after?string

An agreement_id: the page starts after it.

limit?integer

1 to 100, default 25.

Response Body

Success.

application/json
  1. response
data?array<>

The list.

has_more?boolean

true when there is another page.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/usage/agreements'
Example Response
{  "data": [    {      "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    }  ],  "has_more": false}

Overview

Previous Page

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