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 inentitlementshasused,included,percent(rounded down,nullwhen nothing is included) andamount(before prepaid credit).period_endisnullwhen 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, ormewith a shopper's token. It is not thecustomer_idof 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_nameis the name of what the customer bought. - Cached for 5 minutes. With usage billing turned off,
datais 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). Herecustomer_idis your own id, as sent inexternal_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_idis your own id from the agreement, not the Comecero customer id.thresholdis the threshold crossed: 50, 80 or 100.percentis rounded down, so 100 means everything included is used.period_endisnullwhen 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.
How usage is billed
Billing periods, late usage, usage on the renewal invoice, the separate usage invoice, prepaid credit, billing runs, held bills and test mode.
Usage meter API
The one usage meter route your server calls. Send usage events to POST /v1/events with a usage key, and read every field, answer and status code.