---
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.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1
});
```
```typescript Track with idempotency
await autumn.track({
customerId: "cus_123",
featureId: "api_calls",
value: 1,
idempotencyKey: "request_abc123" // Prevents duplicate tracking on retry
});
```
```typescript Credit balance (negative value)
await autumn.track({
customerId: "cus_123",
featureId: "seats",
value: -1 // Increases balance when removing a seat
});
```
```typescript Async (fire-and-forget)
await autumn.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1,
async: true // Returns 202 immediately; usage processed in the background
});
```
### 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.
If true, enqueue the event for asynchronous processing and return 202 immediately. The response will not include balance information.
A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
Must be true to enable locking.
Unix timestamp (ms) when the lock automatically expires and releases the held balance.
### 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.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
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.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
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 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.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
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.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
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.
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.
ID of the underlying balance row that was deducted from (customer_entitlement or rollover).
The feature this balance belongs to.
ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple).
Reset configuration for the balance this deduction came from, or null if the balance doesn't 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.
Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value).
```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
}
]
},
"deductions": [
{
"balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2",
"feature_id": "messages",
"plan_id": "pro",
"reset": {
"interval": "month",
"resets_at": 1781288736881
},
"value": 1
}
]
}
```