Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.batchTrack([
  {
    customerId: "cus_123",
    featureId: "messages",
    value: 1,
  },
  {
    customerId: "cus_123",
    eventName: "message.sent",
    value: 1,
  },
]);

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.batch_track(
    request=[
        {
            "customer_id": "cus_123",
            "feature_id": "messages",
            "value": 1,
        },
        {
            "customer_id": "cus_123",
            "event_name": "message.sent",
            "value": 1,
        },
    ],
)

curl --request POST \
  --url https://api.useautumn.com/v1/balances.batch_track \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
[
  {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "value": 1
  },
  {
    "customer_id": "cus_123",
    "event_name": "message.sent",
    "value": 1
  }
]
'

{
  "success": true
}

Balances

Batch Track Usage

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

balances.batch_track

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.batchTrack([
  {
    customerId: "cus_123",
    featureId: "messages",
    value: 1,
  },
  {
    customerId: "cus_123",
    eventName: "message.sent",
    value: 1,
  },
]);

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.batch_track(
    request=[
        {
            "customer_id": "cus_123",
            "feature_id": "messages",
            "value": 1,
        },
        {
            "customer_id": "cus_123",
            "event_name": "message.sent",
            "value": 1,
        },
    ],
)

curl --request POST \
  --url https://api.useautumn.com/v1/balances.batch_track \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
[
  {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "value": 1
  },
  {
    "customer_id": "cus_123",
    "event_name": "message.sent",
    "value": 1
  }
]
'

{
  "success": true
}

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 },
]);

await autumn.balances.batchTrack([
  { customerId: "cus_123", featureId: "ai_messages", value: 5 },
  { customerId: "cus_123", featureId: "api_calls",   value: 12 },
  { customerId: "cus_123", featureId: "seats",       entityId: "team_a", value: 1 },
]);

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)

Body Parameters

Authorizations

Authorization

string

header

required

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

Headers

x-api-version

string

default:2.3.0

required

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 (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.

Minimum string length: 1

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.

Show child attributes

timestamp

integer

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

Required range: 0 < x <= 9007199254740991

overage_behavior

enum<string>

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.

Available options:

cap,

overflow

async

boolean

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

lock

object

Show child attributes

Example:

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

Response

202 - application/json

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.

success

any

required

⌘I

Billing

Balances

Customers

Authorization

Events

Entities

Plans

Features

Rewards & Referrals

Webhook Events

Platform (Beta)

Batch Track Usage

Common Use Cases

Partial-Failure Semantics

Limits

Body Parameters

Authorizations

Headers

Body

Response

​Common Use Cases

​Partial-Failure Semantics

​Limits

​Body Parameters

Authorizations

Headers

Body

Response

Common Use Cases

Partial-Failure Semantics

Limits

Body Parameters