Skip to main content
POST
/
v1
/
balances.track
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.track({
  customerId: "cus_123",
  featureId: "messages",
  value: 1,
});
{
  "customer_id": "cus_123",
  "value": 1,
  "balance": {
    "feature_id": "messages",
    "granted": 100,
    "remaining": 72,
    "usage": 28,
    "unlimited": false,
    "overage_allowed": false,
    "max_purchase": null,
    "next_reset_at": 1773851121437,
    "breakdown": [
      {
        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
        "plan_id": "pro_plan",
        "included_grant": 100,
        "prepaid_grant": 0,
        "remaining": 72,
        "usage": 28,
        "unlimited": false,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": null,
        "expires_at": null
      }
    ]
  },
  "deductions": [
    {
      "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2",
      "feature_id": "messages",
      "plan_id": "pro",
      "reset": {
        "interval": "month",
        "resets_at": 1781288736881
      },
      "value": 1
    }
  ]
}
Track records usage events to decrement a customer’s balance. Use this to meter feature consumption like API calls, messages sent, or credits used.

​
Common Use Cases

await autumn.track({
  customerId: "cus_123",
  featureId: "ai_messages",
  value: 1
});

​
Body Parameters

​
Response

{
  "customer_id": "cus_123",
  "value": 1,
  "balance": {
    "feature_id": "messages",
    "granted": 100,
    "remaining": 72,
    "usage": 28,
    "unlimited": false,
    "overage_allowed": false,
    "max_purchase": null,
    "next_reset_at": 1773851121437,
    "breakdown": [
      {
        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
        "plan_id": "pro_plan",
        "included_grant": 100,
        "prepaid_grant": 0,
        "remaining": 72,
        "usage": 28,
        "unlimited": false,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": null,
        "expires_at": null
      }
    ]
  },
  "deductions": [
    {
      "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2",
      "feature_id": "messages",
      "plan_id": "pro",
      "reset": {
        "interval": "month",
        "resets_at": 1781288736881
      },
      "value": 1
    }
  ]
}

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

​
async
boolean

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

​
lock
object

Response

OK

​
customer_id
string
required

The ID of the customer whose usage was tracked.

​
value
number
required

The amount of usage that was recorded.

​
balance
object
required

The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.

Example:
{
  "feature_id": "messages",
  "granted": 100,
  "remaining": 72,
  "usage": 28,
  "unlimited": false,
  "overage_allowed": false,
  "max_purchase": null,
  "next_reset_at": 1773851121437,
  "breakdown": [
    {
      "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
      "plan_id": "pro_plan",
      "included_grant": 100,
      "prepaid_grant": 0,
      "remaining": 72,
      "usage": 28,
      "unlimited": false,
      "reset": {
        "interval": "month",
        "resets_at": 1773851121437
      },
      "price": null,
      "expires_at": null
    }
  ]
}
​
entity_id
string

The ID of the entity, if entity-scoped tracking was performed.

​
event_name
string

The event name that was tracked, if event_name was used instead of feature_id.

​
balances
object

Map of feature_id to updated balance for the tracked feature and any related features (e.g. linked credit systems). Value is null when the customer has no balance for that feature.

​
deductions
object[]

Per-balance breakdown of what this event deducted. A single event can consume from multiple balance rows when credit systems or rollovers are involved; this surfaces each one so callers can build per-feature usage views without polling.