# Report usage events

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

Source: https://help.boltapp.com/products/bolt-subscriptions/usage-events

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]

```http title="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](/getting-started/api-keys).

```bash title="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]

```json title="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" }
    }
  ]
}
```

| 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](/products/bolt-subscriptions/meters#event-types-bolt-supports-today). Unknown types are rejected.                                                                                                                                                                                                                                                                                 |
| `quantity`               | Yes      | Decimal string. Negative values are rejected except for delta-style event types; see [quantity sign rules](#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](/products/bolt-subscriptions/usage-invoicing#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 [#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 [#response]

Every event gets an individual result; a valid request returns `202 Accepted` even when some events are rejected. Check each result.

```json title="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" }
  ]
}
```

| 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 [#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](/products/bolt-subscriptions/usage-invoicing#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 [#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 [#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.

## Related [#related]

* [Usage-based billing](/products/bolt-subscriptions/usage-based-billing)
* [Usage alerts](/products/bolt-subscriptions/usage-alerts)
