import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.track({
customerId: "cus_123",
featureId: "messages",
value: 1,
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.track(
customer_id="cus_123",
feature_id="messages",
value=1,
)curl --request POST \
--url https://api.useautumn.com/v1/balances.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",
"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 Usage
Records usage for a customer feature. Queued by default; pass async: false to apply it before responding with updated balances.
Use this after an action happens to decrement usage, or send a negative value to credit balance back.
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.track({
customerId: "cus_123",
featureId: "messages",
value: 1,
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.track(
customer_id="cus_123",
feature_id="messages",
value=1,
)curl --request POST \
--url https://api.useautumn.com/v1/balances.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",
"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
}
]
}
Common Use Cases
await autumn.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1
});
await autumn.track(
{
customerId: "cus_123",
featureId: "api_calls",
value: 1
},
{ headers: { "Idempotency-Key": "request_abc123" } } // Retries with the same key are rejected with a 409
);
await autumn.track({
customerId: "cus_123",
featureId: "seats",
value: -1 // Increases balance when removing a seat
});
await autumn.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1,
async: true // Returns 202 immediately; usage processed in the background
});
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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
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.
1The 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.
Show child attributes
Show child attributes
Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.
0 < x <= 9007199254740991How 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.
cap, overflow Defaults to true: the event is queued and the response is a 202 with balance: null. Set to false to apply the usage before responding with a 200 and the updated balance.
Response
OK
The ID of the customer whose usage was tracked.
The amount of usage that was recorded.
The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.
Show child attributes
Show child attributes
{
"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
}
]
}
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.
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes