comecerodocs
Usage billing

Follow usage

See usage this period so far, the shopper's own usage, the events behind a bill, and webhook alerts when a customer nears their allowance.

Ways to see usage before and after it is billed. All times are in UTC.

This period so far

For each agreement, Comecero works out the usage not billed yet the same way the next invoice will: what was used, what the plan includes, and what the usage above the allowance comes to so far (before prepaid credit).

  • In the dashboard: Usage Billing, the Customers tab, open the customer. The This period so far card shows it per metric, with the Estimated usage charge.
  • With the API: Get usage this period so far (GET /api/v1/usage/agreements/{agreement_id}/current). Each entry in entitlements has used, included, percent (rounded down, null when nothing is included) and amount (before prepaid credit). period_end is null when the subscription has no next renewal.

It is cached for 5 minutes, so it can be a few minutes behind.

The shopper's own usage

Customers see their own usage on their account in your shop: under Subscriptions, the Usage this period card shows each metric with what they used, what their plan includes, and a bar with the percent used. It shows no prices or amounts: the invoice says what is owed. It only appears for plans billed by use.

Your own app or customer portal can read the same with:

curl https://api.comecero.com/api/v1/customers/me/usage \
  -H "Authorization: Bearer $SHOPPER_TOKEN"
{
  "object": "list",
  "data": [
    {
      "object": "customer_usage",
      "subscription_id": "SB0123456789",
      "plan_name": "Pro",
      "period_start": "2026-11-01T00:00:00Z",
      "period_end": "2026-12-01T00:00:00Z",
      "as_of": "2026-11-12T10:00:00Z",
      "metrics": [
        { "metric_name": "AI tokens", "unit_label": "token", "used": 830000, "included": 1000000, "percent": 83 }
      ]
    }
  ]
}

See Get a customer's usage this period.

  • {customer_id} is the Comecero customer id of the subscription's customer, or me with a shopper's token. It is not the customer_id of the agreement, which is your own id. A shopper's token reads only its own customer. A secret token can read any customer.
  • One entry per active agreement on the customer's subscriptions, at most 20. plan_name is the name of what the customer bought.
  • Cached for 5 minutes. With usage billing turned off, data is empty: a shopper never sees an error about it.

The events behind a bill

To check a bill or answer a dispute, look up a customer's events one UTC day at a time, up to 24 months back:

  • In the dashboard: Usage Billing, the Customers tab, open the customer, then View events. Pick a day and, if you like, a metric. You see each event's time, quantity, operation id and properties.
  • With the API: List a customer's events (GET /api/v1/usage/events?customer_id=...&date=YYYY-MM-DD). Here customer_id is your own id, as sent in external_customer_id.

Events show here a few minutes after they are counted. Totals and invoices are never delayed by this.

The meter counts events for any external_customer_id, with or without an agreement. Events for an id with no agreement are counted but never billed. Check a new customer's events here to catch a wrong id early.

For totals over any range of whole hours (up to 366 days), use Read counted usage (GET /api/v1/usage/summary?customer_id=...&metric_key=...&from=...&to=...). It answers the total and each hour's value.

Usage alerts

Subscribe to the webhook event usage:threshold_reached (in the dashboard: Webhooks > Event Subscriptions) to hear when a customer passes 50%, 80% or 100% of what their plan includes in the period not billed yet. Use it to send "running low" emails or offer an upgrade.

  • Each threshold is sent once per entitlement and billing period.
  • Checked every hour. If a customer jumps past several thresholds at once, only the highest is sent.
  • Only entitlements with an included allowance send alerts.
  • No alerts are sent while usage billing is turned off for your account.

Create the subscription in the dashboard or with the API. Send "active": true: a new event subscription is off until it is turned on.

curl -X POST https://api.comecero.com/api/v1/event_subscriptions \
  -H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "usage:threshold_reached",
    "method": "http",
    "format": "json",
    "destination": "https://example.com/webhooks/comecero",
    "active": true
  }'

Comecero then posts each event to your URL, with type set to usage:threshold_reached. See the webhooks guide for deliveries and signatures. The usage alert is in the event's data:

{
  "object": "usage_alert",
  "agreement_id": "agr_8412",
  "entitlement_id": "ent_8412_tokens",
  "customer_id": "cust_8412",
  "metric_id": "met_ai_tokens",
  "metric_key": "ai_tokens",
  "threshold": 80,
  "percent": 83,
  "used": 830000,
  "included": 1000000,
  "period_start": "2026-11-01T00:00:00Z",
  "period_end": "2026-12-01T00:00:00Z"
}
  • customer_id is your own id from the agreement, not the Comecero customer id.
  • threshold is the threshold crossed: 50, 80 or 100.
  • percent is rounded down, so 100 means everything included is used.
  • period_end is null when the subscription has no next renewal.

A delivery looks like this (some event fields are left out here):

{
  "object": "event",
  "event_id": "EV0123456789",
  "type": "usage:threshold_reached",
  "test": false,
  "account_id": "AB1234",
  "date_created": "2026-11-24T14:00:12Z",
  "data": {
    "object": "usage_alert",
    "agreement_id": "agr_8412",
    "entitlement_id": "ent_8412_tokens",
    "customer_id": "cust_8412",
    "metric_id": "met_ai_tokens",
    "metric_key": "ai_tokens",
    "threshold": 100,
    "percent": 104,
    "used": 1040000,
    "included": 1000000,
    "period_start": "2026-11-01T00:00:00Z",
    "period_end": "2026-12-01T00:00:00Z"
  }
}

Use customer_id (your own id) and metric_key to find the customer in your app. Ideas: email "you have used 80% of your tokens" at 80, offer an upgrade or a credit top-up at 100, or stop usage in your app at 100 when the entitlement's overage_policy is block.

On this page