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.
The usage meter is a separate service from the Comecero API, at https://usage.comecero.com. Call it from your server: it does not answer browsers. Your app calls one route on it, to send usage events. It does not take Comecero API tokens, only usage keys. For a walk-through, see Send Usage.
Send usage events
POST https://usage.comecero.com/v1/events
Headers
| Header | Value |
|---|---|
Authorization | Bearer apk_live_... or Bearer apk_test_... |
Content-Type | application/json |
The key decides the account and the mode (live or test). Nothing in the body can change them.
Body
| Field | Type | Required | Description |
|---|---|---|---|
events | array | Yes | 1 to 1,000 events. The whole body is at most 1 MiB. |
Each event:
| Field | Type | Required | Description |
|---|---|---|---|
operation_id | string | Yes | 1 to 128 of A-Z a-z 0-9 _ . : -. Unique per metric for 35 days. Resending it is safe. |
external_customer_id | string | Yes | 1 to 128 of A-Z a-z 0-9 _ . : -. Your id for the customer, the customer_id of their billing agreement. No emails or card numbers. |
metric_key | string | Yes | 1 to 64 of a-z 0-9 _ . -. A metric's event_key. |
quantity | string or number | Yes | 0 or more, at most 12 digits before the point and 6 after. A number must print exactly (no exponent). |
timestamp | string | No | ISO 8601 with a time zone. At most 30 days old and 5 minutes ahead. Defaults to now. Counted in its UTC hour. |
properties | object | No | Up to 20, only the metric's allowed_properties. Values are strings (up to 256 characters), finite numbers or booleans. |
Card numbers (any bare run of 13 to 19 digits, see the rules), card track data, emails and IP addresses are refused in operation_id, external_customer_id and property values.
{
"events": [
{
"operation_id": "req_7Hk2p9",
"external_customer_id": "cust_8412",
"metric_key": "ai_tokens",
"quantity": "1250",
"timestamp": "2026-11-01T09:41:07Z",
"properties": { "model": "large" }
}
]
}Answer
{
"counted": 1,
"duplicate": 0,
"conflict": 0,
"rejected": 0,
"retry": 0,
"results": [
{ "index": 0, "operation_id": "req_7Hk2p9", "status": "counted" }
]
}| Field | Type | Description |
|---|---|---|
counted, duplicate, conflict, rejected, retry | integer | How many events got each answer. |
results | array | One answer per event, in the order sent. |
results[].index | integer | The event's place in events, from 0. |
results[].operation_id | string | The event's operation_id, when it was readable. |
results[].status | string | counted, duplicate, conflict, rejected or retry. See answers. |
results[].code | string | For rejected: why. See what is rejected and why. |
results[].field | string | For rejected: where, for example properties.order_ref. Never the value. |
Status codes
| Status | Meaning |
|---|---|
200 | Every event has a final answer: counted, duplicate, conflict or rejected. |
429 | Some events got retry, or the account sent over 5,000 events or 50 requests this second (too_many_requests, nothing counted). Resend the whole batch: counted events come back as duplicate. |
400 | The request can't be used: { "error": "<code>" } with empty_body, invalid_json, events_missing, events_empty, or too_many_events (over 1,000). |
401 | No Authorization header ({ "message": "Unauthorized" }). |
403 | The usage key is unknown, revoked, for the other mode, not active yet, or in the wrong format ({ "message": "Forbidden" }). |
413 | body_too_large: the body is over 1 MiB. |
503 | try_again: a temporary problem. Resend the batch. |
Rules
- Exactly once. An event is identified by its metric and
operation_id. The first one sent is counted. The same one again with the sameexternal_customer_id,quantityandtimestampis aduplicate; with a different one it is aconflict, and the first one stays. - Counted right away. An event that is
countedis in the totals at once. Billing reads them when the period ends. - Late events are billed. An event for an hour that is already billed is billed on the next invoice as a Late usage line, as long as it is at most 30 days old.
- Any customer id is counted. Only ids that are the
customer_idof a billing agreement are billed. - No negatives. Corrections are made in Comecero, not in the meter.
- Unknown metrics are refused. A metric must exist, be
active, and have reached the meter (usually seconds after you create it).
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.
Usage billing API
Every usage billing route on the Comecero API, grouped by resource, with who may call it and a link to its full page in the API reference.