const options = {
method: 'POST',
headers: {
'x-api-version': '<x-api-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({customer_id: 'cus_123', statuses: ['expired']})
};
fetch('https://api.useautumn.com/v1/balances.list', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.useautumn.com/v1/balances.list"
payload = {
"customer_id": "cus_123",
"statuses": ["expired"]
}
headers = {
"x-api-version": "<x-api-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.useautumn.com/v1/balances.list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"statuses": [
"expired"
]
}
'{
"list": [
{
"id": "bonus_credits",
"plan_id": null,
"included_grant": 50,
"prepaid_grant": 0,
"remaining": 0,
"usage": 50,
"unlimited": false,
"reset": {
"interval": "one_off",
"resets_at": null
},
"price": null,
"expires_at": 1771999921437,
"feature_id": "messages",
"status": "expired",
"rollovers": [],
"customer_id": "cus_123",
"entity_id": null,
"created_at": 1769904000000
}
],
"has_more": false,
"next_cursor": null
}
List Balances
Lists individual balances (one row per grant) across customers, live or expired: plan balances, standalone balances, top-ups, and pooled balances. Pages may hold fewer than limit rows while has_more is true.
const options = {
method: 'POST',
headers: {
'x-api-version': '<x-api-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({customer_id: 'cus_123', statuses: ['expired']})
};
fetch('https://api.useautumn.com/v1/balances.list', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.useautumn.com/v1/balances.list"
payload = {
"customer_id": "cus_123",
"statuses": ["expired"]
}
headers = {
"x-api-version": "<x-api-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.useautumn.com/v1/balances.list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"statuses": [
"expired"
]
}
'{
"list": [
{
"id": "bonus_credits",
"plan_id": null,
"included_grant": 50,
"prepaid_grant": 0,
"remaining": 0,
"usage": 50,
"unlimited": false,
"reset": {
"interval": "one_off",
"resets_at": null
},
"price": null,
"expires_at": 1771999921437,
"feature_id": "messages",
"status": "expired",
"rollovers": [],
"customer_id": "cus_123",
"entity_id": null,
"created_at": 1769904000000
}
],
"has_more": false,
"next_cursor": null
}
balances.create, top-ups, and pooled balances. By default only active balances are returned; pass statuses: ["expired"] for balances whose plan expired or whose expires_at has passed.
Pass plan_id: null to list only balances that don’t come from a plan. Rollovers are returned on the balance they belong to.
limit rows (even zero) while has_more is true. Keep paginating until has_more is false.Body Parameters
Response
{
"list": [
{
"id": "bonus_credits",
"plan_id": null,
"included_grant": 50,
"prepaid_grant": 0,
"remaining": 0,
"usage": 50,
"unlimited": false,
"reset": {
"interval": "one_off",
"resets_at": null
},
"price": null,
"expires_at": 1771999921437,
"feature_id": "messages",
"status": "expired",
"rollovers": [],
"customer_id": "cus_123",
"entity_id": null,
"created_at": 1769904000000
}
],
"has_more": false,
"next_cursor": null
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
Only return rows for this customer. Omit to list across every customer.
Only return rows for this entity. Requires customer_id.
Number of items to return. Default 50, hard ceiling 200.
1 <= x <= 200Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages.
Statuses to include. Defaults to active. A balance is expired when its plan expired, or when a standalone balance passed its expires_at.
1active, expired Only return balances from this plan. Pass null for standalone balances only (top-ups, balances.create, rollovers).
Only return balances for this feature.
Response
OK
Rows on this page.
Show child attributes
Show child attributes
Whether more results exist. A page may hold fewer than limit items (even zero) while has_more is true, so paginate until has_more is false.
Pass as start_cursor to fetch the next page. Null when has_more is false.