Report usage (metered)
POST/v1/usage
Reports usage for metered billing. Accepts a single record or a { records: [...] } batch of up to 100 items. Each record must identify the subscription item by subscription_item_id or by product_slug + customer_id (recommended for external integrations). The price/product must be configured with usage_type=metered and the subscription must be active or trialing. Use idempotency_key to avoid duplicates — when a key was already seen the response is flagged with duplicate: true. Batches with partial failures return 207 Multi-Status.
Request
Responses
- 200
- 207
- 400
- 401
- 403
- 404
- 422
- 429
- 500
Processing result (single record or batch).
Processing result (single record or batch).
Request body failed validation.
Missing or invalid bearer token.
Token is valid but lacks permission for this operation.
Resource not found in the current organization.
Request body failed validation.
Rate limit exceeded.
Unexpected server error.