---
title: "Track Usage"
openapi: "openapi POST /v1/balances.track"
---
import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";
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
```typescript Track single usage
await autumn.balances.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1
});
```
```typescript Track with idempotency
await autumn.balances.track({
customerId: "cus_123",
featureId: "api_calls",
value: 1,
idempotencyKey: "request_abc123" // Prevents duplicate tracking on retry
});
```
```typescript Credit balance (negative value)
await autumn.balances.track({
customerId: "cus_123",
featureId: "seats",
value: -1 // Increases balance when removing a seat
});
```
### Body Parameters
The ID of the customer.
The ID of the feature to track usage for. Required if event_name is not provided.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.
The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).
Additional properties to attach to this usage event.
Unique key to prevent duplicate event recording. Safely retry requests without creating duplicate usage.
### Response
The ID of the customer whose usage was tracked.
The ID of the entity, if entity-scoped tracking was performed.
The event name that was tracked, if event_name was used instead of feature_id.
The amount of usage that was recorded.
The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.
The feature ID this balance is for.
The full feature object if expanded.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
The number of units per billing increment (eg. $9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Map of feature_id to updated balance when tracking by event_name affects multiple features.
The feature ID this balance is for.
The full feature object if expanded.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
The number of units per billing increment (eg. $9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
```json 200
{
"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
}
]
}
}
```