Skip to main content
POST
Typescript (SDK)
Lists what changed one customer’s balance of a feature, newest first by when Autumn recorded it. Each entry says why the balance changed (why), who made the change (actor), and the balance before and after, with each balance it moved in breakdown. Tracks between two other entries are grouped into one track_group per UTC day. To list the tracks in a group, call again with the group’s id as track_group_id.
Balance history is rolling out and isn’t available for every customer yet; coverage says whether it is for this one. coverage.recording is whether Autumn is recording every change to this customer’s balance now: while it is false, some or all changes may be missing. There are no entries from before coverage.since.
An adjustment entry is a change made outside Autumn’s usual flow, for example when seats changed with a license update or expired grants were cleared. why.source names what made it, from the same list as a plan change’s why.action; over time these changes will appear as regular entries with the same value, so a filter on it keeps working. why.writes lists the writes Autumn knows made it, with who made each. When Autumn knows the one write that made the change, recorded_at is when it happened and the totals on either side are exact, and breakdown lists each balance whose share of it Autumn can tell. Otherwise why.window gives the stretch between the entries around it, and usage in that stretch is marked approximate with reason adjustment. Either way, usage before the change on a balance whose share Autumn can’t tell is marked approximate with reason adjustment_share. A page can end just before such a write, so the next page can still place it. When source is null and writes is empty, Autumn can’t say what made the change, which doesn’t mean nothing did; an adjustment from before the customer’s id was changed is one example.
Known limit: if a balance was changed outside Autumn’s usual flow, and the entry before that change is more than 90 days old, usage listed between them may show as exact (why.approximate is null) when it isn’t.
before and after on a track or track group are worked out from the balances around them. why.approximate is set when one of them is an estimate, and says why.
Pages hold up to limit entries (default 50, at most 200). A page can hold fewer while has_more is true, so keep paginating with next_cursor until has_more is false. Tracks are kept for 90 days. Further back, the list holds the other entries only, and the amounts between them are marked approximate; Aggregate Balance Ledger charts up to 400 days.

​
Body Parameters

​
Response

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.6.0
required

Body

application/json
​
customer_id
string
required

The customer whose balance history to list.

Minimum string length: 1
​
feature_id
string
required

The feature whose balance to list. Tracks that this feature's balance paid for are included, whatever feature they named.

Minimum string length: 1
​
entity_id
string

List this entity's own balance of the feature. For an entity with no balance of its own, the customer's balance is listed, limited to changes for this entity.

Minimum string length: 1
​
limit
integer
default:50

Number of items to return. Default 50, hard ceiling 200.

Required range: 1 <= x <= 200
​
start_cursor
string
default:""

Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages.

​
custom_range
object

Only entries that happened in this range.

​
recorded_range
object

Only entries Autumn recorded in this range.

​
track_group_id
string

The id of a track_group entry: lists exactly that group's tracks, one by one. tracks and recorded_range are then ignored.

Minimum string length: 1
​
tracks
enum<string>
default:grouped

grouped folds the tracks between two other entries into one track_group per UTC day; individual lists each track and needs a custom_range or recorded_range with both start and end, or a track_group_id.

Available options:
grouped,
individual

Response

200 - application/json

OK

​
list
object[]
required

Rows on this page.

​
has_more
boolean
required

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.

​
next_cursor
string | null
required

Pass as start_cursor to fetch the next page. Null when has_more is false.

​
entity_id
string | null
required

The entity whose own balance is listed, or null for the customer's.

​
coverage
object
required

How much of this customer's balance history Autumn holds. Balance history is rolling out and isn't available for every customer yet; coverage says whether it is for this one.

​
current
object | null
required

The balance now, on the first page of a listing with no custom_range or recorded_range; null otherwise and for an unlimited balance.