comecerodocs
Usage billing

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

HeaderValue
AuthorizationBearer apk_live_... or Bearer apk_test_...
Content-Typeapplication/json

The key decides the account and the mode (live or test). Nothing in the body can change them.

Body

FieldTypeRequiredDescription
eventsarrayYes1 to 1,000 events. The whole body is at most 1 MiB.

Each event:

FieldTypeRequiredDescription
operation_idstringYes1 to 128 of A-Z a-z 0-9 _ . : -. Unique per metric for 35 days. Resending it is safe.
external_customer_idstringYes1 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_keystringYes1 to 64 of a-z 0-9 _ . -. A metric's event_key.
quantitystring or numberYes0 or more, at most 12 digits before the point and 6 after. A number must print exactly (no exponent).
timestampstringNoISO 8601 with a time zone. At most 30 days old and 5 minutes ahead. Defaults to now. Counted in its UTC hour.
propertiesobjectNoUp 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" }
  ]
}
FieldTypeDescription
counted, duplicate, conflict, rejected, retryintegerHow many events got each answer.
resultsarrayOne answer per event, in the order sent.
results[].indexintegerThe event's place in events, from 0.
results[].operation_idstringThe event's operation_id, when it was readable.
results[].statusstringcounted, duplicate, conflict, rejected or retry. See answers.
results[].codestringFor rejected: why. See what is rejected and why.
results[].fieldstringFor rejected: where, for example properties.order_ref. Never the value.

Status codes

StatusMeaning
200Every event has a final answer: counted, duplicate, conflict or rejected.
429Some 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.
400The request can't be used: { "error": "<code>" } with empty_body, invalid_json, events_missing, events_empty, or too_many_events (over 1,000).
401No Authorization header ({ "message": "Unauthorized" }).
403The usage key is unknown, revoked, for the other mode, not active yet, or in the wrong format ({ "message": "Forbidden" }).
413body_too_large: the body is over 1 MiB.
503try_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 same external_customer_id, quantity and timestamp is a duplicate; with a different one it is a conflict, and the first one stays.
  • Counted right away. An event that is counted is 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_id of 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).

On this page