Report usage events
Send usage events to Bolt so metered consumption appears on subscriber invoices.
Report consumption by POSTing batches of usage events. Bolt validates each event independently, deduplicates on your event ID, and aggregates accepted events into the subscription's metered totals.
Endpoint
POST /v1/usage_eventsSend both your merchant API key and your publishable key, in the X-API-Key and X-Publishable-Key headers. A request missing either is rejected. See API keys.
curl -X POST https://api-sandbox.boltapp.com/v1/usage_events \
-H "Content-Type: application/json" \
-H "X-API-Key: $BOLT_API_KEY" \
-H "X-Publishable-Key: $BOLT_PUBLISHABLE_KEY" \
-d @events.jsonRequest
{
"events": [
{
"entity_type": "subscription",
"entity_id": "SUB-123456789",
"event_type": "api_calls",
"quantity": "250",
"start_time": "2026-09-24T10:00:00Z",
"end_time": "2026-09-24T11:00:00Z",
"merchant_event_id": "usage-2026-09-24T10-shard4",
"properties": { "region": "us-west" }
}
]
}| Field | Required | Notes |
|---|---|---|
entity_type | Yes | The kind of entity the usage belongs to. Use subscription. |
entity_id | Yes | The subscription's public ID. The subscription must be active, trialing, or past due. A canceled subscription still accepts usage for its final period until that period is billed. A paused subscription rejects usage. |
event_type | Yes | A registered event type. Unknown types are rejected. |
quantity | Yes | Decimal string. Negative values are rejected except for delta-style event types; see quantity sign rules. |
start_time, end_time | Yes | RFC 3339. The span the usage covers. end_time must not precede start_time and the span must not exceed 31 days. start_time must fall inside the acceptance window: no further back than the Usage acceptance window (default 72 hours, set in your division billing settings) and no more than 5 minutes in the future. |
merchant_event_id | Yes | Your idempotency key, at most 255 characters. Resending the same ID never double-counts. |
properties | No | Arbitrary JSON validated against the event type's schema, at most 8 KB serialized. Meters can filter on properties. |
Limits
- 1 to 500 events per request.
- Request body at most 6 MiB.
- Rate limited per division. On
429, honor theRetry-Afterheader and retry with backoff.
Response
Every event gets an individual result; a valid request returns 202 Accepted even when some events are rejected. Check each result.
{
"results": [
{ "merchant_event_id": "usage-2026-09-24T10-shard4", "status": "recorded" },
{ "merchant_event_id": "usage-2026-09-24T09-shard4", "status": "duplicate" },
{ "merchant_event_id": "bad-evt-1", "status": "rejected", "reason": "quantity_negative" }
]
}| Status | Meaning |
|---|---|
recorded | Accepted and counted toward the meter. |
duplicate | An event with this merchant_event_id was already recorded. Not counted again. |
rejected | Failed validation. reason says why. Fix and resend with a new or same ID. |
Rejection reasons
reason | Cause |
|---|---|
event_malformed | The event is not valid JSON of the expected shape. |
merchant_event_id_invalid | Missing or longer than 255 characters. |
entity_not_found | Unknown entity_type or no such entity_id. |
entity_not_eligible | The subscription can't accept usage, for example because it is paused or fully canceled. |
event_type_not_found | The event_type is not registered. |
properties_schema_invalid | properties does not match the event type's schema. |
properties_too_large | properties exceeds 8 KB serialized. |
out_of_acceptance_window | start_time is outside the acceptance window; see division billing settings. |
invalid_span | end_time precedes start_time, or the span exceeds 31 days. |
quantity_negative | Negative quantity on an event type that does not allow it. |
storage_failure | Transient storage error. Retry the event with the same merchant_event_id. |
Quantity sign rules
Counter-style event types accumulate consumption and reject negative quantities: recorded events are immutable, so a compensating negative event would silently distort the period total. To correct over-reported usage, credit the resulting invoice instead.
Delta-style event types measure changes to a level, such as storage_gb_delta, and accept signed quantities: a negative delta means the level went down, not that a past event is being reversed.
Delivery guidance
- Batch events rather than sending one request per event, and stay within the per-division rate limit.
- Make
merchant_event_iddeterministic from your source data, for example an aggregation window and shard, so retries after timeouts are safe. - Treat
storage_failureas retryable and every other rejection as a bug to fix at the source.