Bolt has moved to boltapp.com. Stores still using bolt.com hosts must update now: see the migration guide.

Skip to content

Report usage events

Send usage events to Bolt so metered consumption appears on subscriber invoices.

View As MarkdownMCP

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

Endpoint
POST /v1/usage_events

Send 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.

Request
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.json

Request

Request
{
  "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" }
    }
  ]
}
FieldRequiredNotes
entity_typeYesThe kind of entity the usage belongs to. Use subscription.
entity_idYesThe 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_typeYesA registered event type. Unknown types are rejected.
quantityYesDecimal string. Negative values are rejected except for delta-style event types; see quantity sign rules.
start_time, end_timeYesRFC 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_idYesYour idempotency key, at most 255 characters. Resending the same ID never double-counts.
propertiesNoArbitrary 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 the Retry-After header 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.

Response
{
  "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" }
  ]
}
StatusMeaning
recordedAccepted and counted toward the meter.
duplicateAn event with this merchant_event_id was already recorded. Not counted again.
rejectedFailed validation. reason says why. Fix and resend with a new or same ID.

Rejection reasons

reasonCause
event_malformedThe event is not valid JSON of the expected shape.
merchant_event_id_invalidMissing or longer than 255 characters.
entity_not_foundUnknown entity_type or no such entity_id.
entity_not_eligibleThe subscription can't accept usage, for example because it is paused or fully canceled.
event_type_not_foundThe event_type is not registered.
properties_schema_invalidproperties does not match the event type's schema.
properties_too_largeproperties exceeds 8 KB serialized.
out_of_acceptance_windowstart_time is outside the acceptance window; see division billing settings.
invalid_spanend_time precedes start_time, or the span exceeds 31 days.
quantity_negativeNegative quantity on an event type that does not allow it.
storage_failureTransient 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_id deterministic from your source data, for example an aggregation window and shard, so retries after timeouts are safe.
  • Treat storage_failure as retryable and every other rejection as a bug to fix at the source.

On this page