Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB

Enqueue up to 1000 usage events for asynchronous processing. Items are validated synchronously up front; validated items are then enqueued via SQS for background deduction by workers. The response returns 202 immediately and does not include balance information. On partial enqueue failure (some items fail to enqueue, others succeed), the endpoint still returns 202 and logs the failures server-side; clients should NOT retry, because retrying re-enqueues the already-succeeded items. A 503 is returned only when zero items were successfully enqueued (queue entirely unavailable) — that case is safe to retry.

post/v1/balances.batch_track

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer.

feature_idstring

The ID of the feature to track usage for. Required if event_name is not provided.

entity_idstring

The ID of the entity for entity-scoped balances (e.g., per-seat limits).

event_namestring

Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.

valuenumber

The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).

propertiesobject

Additional properties to attach to this usage event.

timestampinteger

Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.

overage_behavior'cap' | 'overflow'

How to handle usage that exceeds the available balance. "cap" (default) deducts only what fits, stopping at zero. "overflow" deducts the full value: the balance can go negative and usage limits do not clamp the deduction, though spend limits still apply.

asyncboolean

If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.

Example request

[
  {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "value": 1
  },
  {
    "customer_id": "cus_123",
    "event_name": "message.sent",
    "value": 1
  }
]

Response

Batch accepted. All items passed synchronous validation. Enqueue is best-effort: partial failures (some items enqueued, some not) are logged server-side and are NOT surfaced in the response body; clients must not retry on 202. See the endpoint description for full partial-failure semantics.

{"stackTrail":"paths:/v1/balances.batch_track:post:responses:202:content:application/json:schema:properties:success","oasType":"schema","type":"unknown"}

Example response

{
  "success": true
}