---
title: "POST /v1/balances.batch_track"
method: POST
path: "/v1/balances.batch_track"
---

# POST /v1/balances.batch_track

`POST /v1/balances.batch_track`

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.

## Headers

- `x-api-version` string, required

## Request body

- object[]
  - `customer_id` string, required — The ID of the customer.
  - `feature_id` string — The ID of the feature to track usage for. Required if event_name is not provided.
  - `entity_id` string — The ID of the entity for entity-scoped balances (e.g., per-seat limits).
  - `event_name` string — Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.
  - `value` number — The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).
  - `properties` object — Additional properties to attach to this usage event.
  - `timestamp` integer — 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.
  - `async` boolean — If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.
  - `lock` object
    - `lock_id` string, required — A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
    - `enabled` unknown, required
    - `expires_at` number — Unix timestamp (ms) when the lock automatically expires and releases the held balance.

## Response `202`

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.

- object
  - `success` unknown, required

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/versions/29536933c0dc/schema)