Skip to main content
POST
/
v1
/
balances.batchTrack
TypeScript
await autumn.balances.batchTrack([
  { customerId: "cus_123", featureId: "messages", value: 1 },
  { customerId: "cus_456", featureId: "messages", value: 5 },
]);
{
  "success": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt

Use this file to discover all available pages before exploring further.

Batch track enqueues up to 1000 usage events in a single request. Items are validated synchronously, then enqueued for asynchronous processing. The response returns 202 immediately without balance information — balances are deducted by background workers.Use this when you’re sending high volumes of tracking events and don’t need an immediate balance read for each one.

​
Common Use Cases

await autumn.balances.batchTrack([
  { customerId: "cus_alice", featureId: "ai_messages", value: 1 },
  { customerId: "cus_bob",   featureId: "ai_messages", value: 1 },
  { customerId: "cus_carol", featureId: "ai_messages", value: 3 },
]);

​
Partial-Failure Semantics

Batch track is designed for fire-and-forget metering. On partial failure, the endpoint still returns 202 and logs the failed items server-side. Clients should NOT retry the batch — retrying re-enqueues the already-succeeded items, which causes double-deduction. The trade-off is silent loss of the small subset that didn’t enqueue vs. duplicate processing of the much larger subset that did. For event-logging workloads, gaps are preferable to duplicates. A 503 is returned only when zero items were successfully enqueued (the queue is entirely unavailable). In that case the whole request is safe to retry. If your workload requires per-item delivery guarantees, use the single-event track endpoint with client-side retry semantics instead.

​
Limits

  • Maximum batch size: 1000 items per request
  • Minimum batch size: 1 item
  • Rate limit: 10 requests/second per organization (separate bucket from the single /v1/balances.track limiter)

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
Required array length: 1 - 1000 elements
​
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.

​
event_name
string

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

Minimum string length: 1
​
value
number

The amount of usage to record. Defaults to 1.

​
properties
object

Additional properties to attach to this usage event.

Example:
[
  {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "value": 1
  },
  {
    "customer_id": "cus_456",
    "feature_id": "messages",
    "value": 5
  }
]

Response

Accepted

​
success
boolean
required

Always true. Indicates the batch was accepted (fully or partially enqueued).