> ## Documentation Index > Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt > Use this file to discover all available pages before exploring further. # List Balance Ledger > Lists what changed one customer's balance of a feature, newest first: plan changes, resets, updates, and tracks grouped per UTC day. Each entry says why, who made it, and the balance before and after. coverage says whether history is being recorded for the customer and since when. 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`. > [!NOTE] > > 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. > [!NOTE] > > 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. > [!NOTE] > > `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](https://docs.useautumn.com/api-reference/balances/aggregateBalanceLedger.md) charts up to 400 days. ### Body Parameters The customer whose balance history to list. 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. Number of items to return. Default 50, hard ceiling 200. Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages. The feature whose balance to list. Tracks that this feature's balance paid for are included, whatever feature they named. Only entries that happened in this range. **properties** Only entries that happened at or after this time (epoch milliseconds). Only entries that happened at or before this time (epoch milliseconds). Only entries Autumn recorded in this range. **properties** Only entries Autumn recorded at or after this time (epoch milliseconds). Only entries Autumn recorded at or before this time (epoch milliseconds). The id of a track\_group entry: lists exactly that group's tracks, one by one. tracks and recorded\_range are then ignored. 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. ### Response Rows on this page. **properties** Stable id of the entry. A series change point names it as entry\_id. When it happened (epoch milliseconds), as the caller said, so a backdated track keeps its timestamp. When Autumn recorded it (epoch milliseconds). Entries are listed newest first by this. For a track group, its latest track. For a reset, the end of the cycle it closed. The feature the change named. For a track on a credit system, the feature the track named, not the one that paid. The entity the change was for, or null for the customer. What changed the balance. track: one balances.track call. track\_group: the tracks between two other entries, one group per UTC day. plan\_change: a plan was attached, changed or removed. adjustment: a change made outside Autumn's usual flow, for example by a license update or a cleanup; source says what made it, from the same list as plan\_change's action, and over time these changes will appear as regular entries with the same value. missing\_history: some history was lost here. reset, update, delete, recalculate and finalize: the balances operation of that name. history\_started: the balance as it was when Autumn began recording it. **properties** The value sent to balances.track; null when the track recorded no event. What the track took from this feature's balances, in this feature's units; negative for a refund. The usage event the track recorded, as in events.list. The event's properties, when tracks are listed individually. What the track took from each balance. **properties** The balance that paid, the same id as in balances.track. In a customer's view of a balance that each entity holds its own share of, the entity whose share paid; null otherwise. What it took from the balance; negative for a refund. Set when before or after is an estimate; null when both are exact. **properties** Why it is an estimate: overage or a refund on a balance several entities share; history that is missing above it; an adjustment Autumn can't place exactly, beside it; or adjustment\_share, a later adjustment that may have changed a balance it drew on by an amount the entries around it don't show. Whether before is an estimate. Whether after is an estimate. **properties** Who made the change: an API key, a customer token, a dashboard member, an integration, or Autumn itself (a usage reset, a lock that expired, a migration, an auto top-up, or Autumn support). unknown when nothing was recorded. The API key id, the customer id for a customer token, the dashboard member's user id, or the migration id; null for the other types. The balance before the change; null when it is not known. **properties** Everything granted on the balance, rollovers included. What was left to use. What had been used. The balance after the change; null when it is not known. **properties** Everything granted on the balance, rollovers included. What was left to use. What had been used. Each balance the change moved, before and after; null for tracks, whose deductions say which balances paid. **properties** The balance that changed, the same id as balance\_id in a track's deductions. The plan the balance comes from, or null for one that does not. The balance before the change; null when it did not exist yet. **properties** What this balance granted; null where it was not recorded. The balance after the change; null when the change removed it. **properties** What this balance granted; null where it was not recorded. 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. The entity whose own balance is listed, or null for the customer's. 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. **properties** Whether Autumn is recording every change to this customer's balance now. While false, some or all changes may be missing (tracks may still be recorded), so a history that is empty or missing changes is expected. The earliest time history covers for this customer (epoch milliseconds), or null when nothing has been recorded yet. There are no entries from before it. The balance now, on the first page of a listing with no custom\_range or recorded\_range; null otherwise and for an unlimited balance. **properties** **properties** Everything granted on the balance, rollovers included. What was left to use. What had been used. The balances behind the totals. Rollovers are not listed; the totals minus these balances is what rollovers hold. **properties** The balance, the same id as balance\_id in a track's deductions. In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. ```json 200 theme={null} { "list": [ { "id": "hist_Y2hhbmdlXzM", "occurred_at": 1761609600000, "recorded_at": 1761609600412, "effective_at": 1761609600000, "feature_id": "messages", "entity_id": null, "why": { "type": "reset" }, "actor": { "type": "reset", "id": null }, "before": { "granted": 1000, "remaining": 120, "usage": 880 }, "after": { "granted": 1000, "remaining": 1000, "usage": 0 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "plan_id": "pro", "before": { "granted": 1000, "remaining": 120, "usage": 880 }, "after": { "granted": 1000, "remaining": 1000, "usage": 0 } } ] }, { "id": "hist_Z3JvdXBfMg", "occurred_at": 1761580800000, "recorded_at": 1761580801207, "effective_at": null, "feature_id": "messages", "entity_id": null, "why": { "type": "track_group", "count": 214, "amount": 380, "occurred_from": 1761523200000, "occurred_to": 1761580800000, "recorded_from": 1761523200530, "recorded_to": 1761580801207, "deductions": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "value": 380 } ], "approximate": null }, "actor": { "type": "secret_key", "id": "key_123" }, "before": { "granted": 1000, "remaining": 500, "usage": 500 }, "after": { "granted": 1000, "remaining": 120, "usage": 880 }, "breakdown": null }, { "id": "hist_cGxhbl8x", "occurred_at": 1761436800000, "recorded_at": 1761436800310, "effective_at": null, "feature_id": "messages", "entity_id": null, "why": { "type": "plan_change", "action": "upgrade", "from_plan_ids": [ "free" ], "to_plan_ids": [ "pro" ] }, "actor": { "type": "secret_key", "id": "key_123" }, "before": { "granted": 100, "remaining": 0, "usage": 100 }, "after": { "granted": 1000, "remaining": 900, "usage": 100 }, "breakdown": [ { "balance_id": "cus_ent_2AbQmZ0oFree11a9Neecl2a2Gc5", "plan_id": "free", "before": { "granted": 100, "remaining": 0, "usage": 100 }, "after": null }, { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "plan_id": "pro", "before": null, "after": { "granted": 1000, "remaining": 900, "usage": 100 } } ] } ], "has_more": true, "next_cursor": "eyJ2IjowLCJ0IjoxNzYxNDM2ODAwMzEwfQ", "entity_id": null, "coverage": { "recording": true, "since": 1759300000000 }, "current": { "totals": { "granted": 1000, "remaining": 960, "usage": 40 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 960, "usage": 40 } ] } } ``` ## OpenAPI ````yaml openapi POST /v1/balances.list_ledger openapi: 3.1.0 info: title: Autumn API version: 2.6.0 servers: - url: https://api.useautumn.com description: Production server security: - secretKey: [] paths: /v1/balances.list_ledger: post: tags: - balances description: >- Lists what changed one customer's balance of a feature, newest first: plan changes, resets, updates, and tracks grouped per UTC day. Each entry says why, who made it, and the balance before and after. coverage says whether history is being recorded for the customer and since when. operationId: listBalanceLedger parameters: - name: x-api-version in: header required: true schema: type: string default: 2.6.0 x-speakeasy-globals-hidden: true requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string minLength: 1 description: The customer whose balance history to list. entity_id: type: string minLength: 1 description: >- 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. limit: type: integer minimum: 1 maximum: 200 default: 50 description: Number of items to return. Default 50, hard ceiling 200. start_cursor: type: string default: '' description: >- Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages. feature_id: type: string minLength: 1 description: >- The feature whose balance to list. Tracks that this feature's balance paid for are included, whatever feature they named. custom_range: type: object properties: start: type: number description: >- Only entries that happened at or after this time (epoch milliseconds). end: type: number description: >- Only entries that happened at or before this time (epoch milliseconds). description: Only entries that happened in this range. recorded_range: type: object properties: start: type: number description: >- Only entries Autumn recorded at or after this time (epoch milliseconds). end: type: number description: >- Only entries Autumn recorded at or before this time (epoch milliseconds). description: Only entries Autumn recorded in this range. track_group_id: type: string minLength: 1 description: >- The id of a track_group entry: lists exactly that group's tracks, one by one. tracks and recorded_range are then ignored. tracks: enum: - grouped - individual type: string default: grouped description: >- 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. required: - customer_id - feature_id title: ListBalanceLedgerParams examples: - customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages tracks: individual recorded_range: start: 1761523200530 end: 1761580801207 example: customer_id: cus_123 feature_id: messages responses: '200': description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string description: >- Stable id of the entry. A series change point names it as entry_id. occurred_at: type: number description: >- When it happened (epoch milliseconds), as the caller said, so a backdated track keeps its timestamp. recorded_at: type: number description: >- When Autumn recorded it (epoch milliseconds). Entries are listed newest first by this. For a track group, its latest track. effective_at: anyOf: - type: number - type: 'null' description: For a reset, the end of the cycle it closed. feature_id: type: string description: >- The feature the change named. For a track on a credit system, the feature the track named, not the one that paid. entity_id: anyOf: - type: string - type: 'null' description: >- The entity the change was for, or null for the customer. why: anyOf: - type: object properties: type: const: track value: anyOf: - type: number - type: 'null' description: >- The value sent to balances.track; null when the track recorded no event. amount: type: number description: >- What the track took from this feature's balances, in this feature's units; negative for a refund. event_id: anyOf: - type: string - type: 'null' description: >- The usage event the track recorded, as in events.list. properties: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: >- The event's properties, when tracks are listed individually. deductions: type: array items: type: object properties: balance_id: type: string description: >- The balance that paid, the same id as in balances.track. entity_id: anyOf: - type: string - type: 'null' description: >- In a customer's view of a balance that each entity holds its own share of, the entity whose share paid; null otherwise. value: type: number description: >- What it took from the balance; negative for a refund. required: - balance_id - entity_id - value description: What the track took from each balance. approximate: anyOf: - type: object properties: reason: enum: - overage - refund - missing_history - adjustment - adjustment_share type: string description: >- Why it is an estimate: overage or a refund on a balance several entities share; history that is missing above it; an adjustment Autumn can't place exactly, beside it; or adjustment_share, a later adjustment that may have changed a balance it drew on by an amount the entries around it don't show. before: type: boolean description: Whether before is an estimate. after: type: boolean description: Whether after is an estimate. required: - reason - before - after - type: 'null' description: >- Set when before or after is an estimate; null when both are exact. required: - type - value - amount - event_id - properties - deductions - approximate - type: object properties: type: const: track_group count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: How many tracks it holds. amount: type: number description: >- What its tracks took from this feature's balances, net of refunds. occurred_from: type: number description: >- When the earliest of its tracks happened (epoch milliseconds). occurred_to: type: number description: >- When the latest of its tracks happened (epoch milliseconds). recorded_from: type: number description: >- When Autumn recorded its first track. Pass the group's id as track_group_id to list exactly its tracks. recorded_to: type: number description: When Autumn recorded its last track. deductions: type: array items: type: object properties: balance_id: type: string description: >- The balance that paid, the same id as in balances.track. entity_id: anyOf: - type: string - type: 'null' description: >- In a customer's view of a balance that each entity holds its own share of, the entity whose share paid; null otherwise. value: type: number description: >- What it took from the balance; negative for a refund. required: - balance_id - entity_id - value description: >- What its tracks took from each balance, summed per balance. Rollovers count under their own ids. approximate: anyOf: - type: object properties: reason: enum: - overage - refund - missing_history - adjustment - adjustment_share type: string description: >- Why it is an estimate: overage or a refund on a balance several entities share; history that is missing above it; an adjustment Autumn can't place exactly, beside it; or adjustment_share, a later adjustment that may have changed a balance it drew on by an amount the entries around it don't show. before: type: boolean description: Whether before is an estimate. after: type: boolean description: Whether after is an estimate. required: - reason - before - after - type: 'null' description: >- Set when before or after is an estimate; null when both are exact. required: - type - count - amount - occurred_from - occurred_to - recorded_from - recorded_to - deductions - approximate - type: object properties: type: const: plan_change action: anyOf: - enum: - new - upgrade - downgrade - renew - add_on - one_off - new_version - scheduled_switch - cancel - uncancel - quantity - manual_topup - auto_topup - set_plans - migration - sync - rollback - restore - license - multi_attach - switch - update - license_seats - license_pool - seat_transition - entity_create - entity_delete - allocation_update - paid_allocated - legacy_attach - legacy_balances - expired_grants - vercel_renewal - scheduled_reset - reward - transfer - reset_schedule - plan_expiry - balance_delete type: string description: >- What changed the balance. One list names both a plan change's action and an adjustment's source, so a change keeps its value when it is recorded the other way. Plan changes: new, upgrade, downgrade, renew, add_on, one_off, new_version, scheduled_switch, cancel, uncancel, quantity, manual_topup, auto_topup (an automatic top-up), set_plans, migration (a plan migration), sync, rollback, restore, license, multi_attach, switch, update. Other changes: license_seats (seats changed by a license update), license_pool (a pooled balance was reset or moved), seat_transition (seats moved between plans), entity_create (an entity was added), entity_delete (an entity was removed), allocation_update (an allocated balance was updated), paid_allocated (a paid allocated balance was set), legacy_attach and legacy_balances (set through the legacy API), expired_grants (expired grants were cleared), vercel_renewal (renewed through Vercel), scheduled_reset (a scheduled usage reset), reward (a reward was granted), transfer (a plan moved to another customer or entity), reset_schedule (a reset date changed), plan_expiry (a plan expired), balance_delete (an expired balance was removed). - const: other description: >- What kind of plan change it was, from the same list as an adjustment's source; other when Autumn can't say. from_plan_ids: type: array items: type: string to_plan_ids: type: array items: type: string required: - type - action - from_plan_ids - to_plan_ids - type: object properties: type: const: adjustment source: anyOf: - enum: - new - upgrade - downgrade - renew - add_on - one_off - new_version - scheduled_switch - cancel - uncancel - quantity - manual_topup - auto_topup - set_plans - migration - sync - rollback - restore - license - multi_attach - switch - update - license_seats - license_pool - seat_transition - entity_create - entity_delete - allocation_update - paid_allocated - legacy_attach - legacy_balances - expired_grants - vercel_renewal - scheduled_reset - reward - transfer - reset_schedule - plan_expiry - balance_delete type: string description: >- What changed the balance. One list names both a plan change's action and an adjustment's source, so a change keeps its value when it is recorded the other way. Plan changes: new, upgrade, downgrade, renew, add_on, one_off, new_version, scheduled_switch, cancel, uncancel, quantity, manual_topup, auto_topup (an automatic top-up), set_plans, migration (a plan migration), sync, rollback, restore, license, multi_attach, switch, update. Other changes: license_seats (seats changed by a license update), license_pool (a pooled balance was reset or moved), seat_transition (seats moved between plans), entity_create (an entity was added), entity_delete (an entity was removed), allocation_update (an allocated balance was updated), paid_allocated (a paid allocated balance was set), legacy_attach and legacy_balances (set through the legacy API), expired_grants (expired grants were cleared), vercel_renewal (renewed through Vercel), scheduled_reset (a scheduled usage reset), reward (a reward was granted), transfer (a plan moved to another customer or entity), reset_schedule (a reset date changed), plan_expiry (a plan expired), balance_delete (an expired balance was removed). - type: 'null' description: >- What adjusted the balance, when every write in writes names the same source; null when Autumn can't say, because no write is known for this stretch or they differ. from: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: The balance just before the adjustment. to: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: The balance just after the adjustment. window: anyOf: - type: object properties: from: type: number description: >- When the older entry around it was recorded. to: anyOf: - type: number - type: 'null' description: >- When the newer entry around it was recorded; null when no newer entry is listed. required: - from - to - type: 'null' description: >- When Autumn can't place the adjustment exactly, the stretch it happened in; usage in that stretch is then marked approximate. Null when recorded_at is when it happened and the entries around it are exact. writes: type: array items: type: object properties: source: enum: - new - upgrade - downgrade - renew - add_on - one_off - new_version - scheduled_switch - cancel - uncancel - quantity - manual_topup - auto_topup - set_plans - migration - sync - rollback - restore - license - multi_attach - switch - update - license_seats - license_pool - seat_transition - entity_create - entity_delete - allocation_update - paid_allocated - legacy_attach - legacy_balances - expired_grants - vercel_renewal - scheduled_reset - reward - transfer - reset_schedule - plan_expiry - balance_delete type: string description: >- What changed the balance. One list names both a plan change's action and an adjustment's source, so a change keeps its value when it is recorded the other way. Plan changes: new, upgrade, downgrade, renew, add_on, one_off, new_version, scheduled_switch, cancel, uncancel, quantity, manual_topup, auto_topup (an automatic top-up), set_plans, migration (a plan migration), sync, rollback, restore, license, multi_attach, switch, update. Other changes: license_seats (seats changed by a license update), license_pool (a pooled balance was reset or moved), seat_transition (seats moved between plans), entity_create (an entity was added), entity_delete (an entity was removed), allocation_update (an allocated balance was updated), paid_allocated (a paid allocated balance was set), legacy_attach and legacy_balances (set through the legacy API), expired_grants (expired grants were cleared), vercel_renewal (renewed through Vercel), scheduled_reset (a scheduled usage reset), reward (a reward was granted), transfer (a plan moved to another customer or entity), reset_schedule (a reset date changed), plan_expiry (a plan expired), balance_delete (an expired balance was removed). actor: type: object properties: type: enum: - secret_key - public_key - customer_jwt - dashboard - stripe - revenuecat - vercel - reset - lock_expiry - migration - auto_topup - autumn - unknown type: string description: >- Who made the change: an API key, a customer token, a dashboard member, an integration, or Autumn itself (a usage reset, a lock that expired, a migration, an auto top-up, or Autumn support). unknown when nothing was recorded. id: anyOf: - type: string - type: 'null' description: >- The API key id, the customer id for a customer token, the dashboard member's user id, or the migration id; null for the other types. required: - type - id request_id: type: string description: The request or job that made the write. recorded_at: type: number description: >- When Autumn recorded the write (epoch milliseconds). required: - source - actor - request_id - recorded_at description: >- The writes Autumn knows made this adjustment, oldest first. Empty means none is known, not that none happened: for example, an adjustment from before the customer's id was changed lists none. required: - type - source - from - to - window - writes - type: object properties: type: const: missing_history required: - type - type: object properties: type: const: reset required: - type - type: object properties: type: const: update remaining: anyOf: - type: number - type: 'null' usage: anyOf: - type: number - type: 'null' add_to_balance: anyOf: - type: number - type: 'null' included_grant: anyOf: - type: number - type: 'null' next_reset_at: anyOf: - type: number - type: 'null' expires_at: anyOf: - type: number - type: 'null' required: - type - remaining - usage - add_to_balance - included_grant - next_reset_at - expires_at - type: object properties: type: const: delete required: - type - type: object properties: type: const: recalculate required: - type - type: object properties: type: const: finalize final_value: anyOf: - type: number - type: 'null' description: >- The value the lock was finalized at, if one was given. required: - type - final_value - type: object properties: type: const: history_started required: - type description: >- What changed the balance. track: one balances.track call. track_group: the tracks between two other entries, one group per UTC day. plan_change: a plan was attached, changed or removed. adjustment: a change made outside Autumn's usual flow, for example by a license update or a cleanup; source says what made it, from the same list as plan_change's action, and over time these changes will appear as regular entries with the same value. missing_history: some history was lost here. reset, update, delete, recalculate and finalize: the balances operation of that name. history_started: the balance as it was when Autumn began recording it. actor: type: object properties: type: enum: - secret_key - public_key - customer_jwt - dashboard - stripe - revenuecat - vercel - reset - lock_expiry - migration - auto_topup - autumn - unknown type: string description: >- Who made the change: an API key, a customer token, a dashboard member, an integration, or Autumn itself (a usage reset, a lock that expired, a migration, an auto top-up, or Autumn support). unknown when nothing was recorded. id: anyOf: - type: string - type: 'null' description: >- The API key id, the customer id for a customer token, the dashboard member's user id, or the migration id; null for the other types. required: - type - id before: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: >- The balance before the change; null when it is not known. after: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: >- The balance after the change; null when it is not known. breakdown: anyOf: - type: array items: type: object properties: balance_id: type: string description: >- The balance that changed, the same id as balance_id in a track's deductions. plan_id: anyOf: - type: string - type: 'null' description: >- The plan the balance comes from, or null for one that does not. before: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- What this balance granted; null where it was not recorded. remaining: type: number usage: type: number required: - granted - remaining - usage - type: 'null' description: >- The balance before the change; null when it did not exist yet. after: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- What this balance granted; null where it was not recorded. remaining: type: number usage: type: number required: - granted - remaining - usage - type: 'null' description: >- The balance after the change; null when the change removed it. required: - balance_id - plan_id - before - after - type: 'null' description: >- Each balance the change moved, before and after; null for tracks, whose deductions say which balances paid. required: - id - occurred_at - recorded_at - effective_at - feature_id - entity_id - why - actor - before - after - breakdown description: Rows on this page. has_more: type: boolean description: >- 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: anyOf: - type: string - type: 'null' description: >- Pass as start_cursor to fetch the next page. Null when has_more is false. entity_id: anyOf: - type: string - type: 'null' description: >- The entity whose own balance is listed, or null for the customer's. coverage: type: object properties: recording: type: boolean description: >- Whether Autumn is recording every change to this customer's balance now. While false, some or all changes may be missing (tracks may still be recorded), so a history that is empty or missing changes is expected. since: anyOf: - type: number - type: 'null' description: >- The earliest time history covers for this customer (epoch milliseconds), or null when nothing has been recorded yet. There are no entries from before it. required: - recording - since description: >- 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: anyOf: - type: object properties: totals: type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage breakdown: type: array items: type: object properties: balance_id: type: string description: >- The balance, the same id as balance_id in a track's deductions. entity_id: anyOf: - type: string - type: 'null' description: >- In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. plan_id: anyOf: - type: string - type: 'null' granted: type: number remaining: type: number usage: type: number required: - balance_id - entity_id - plan_id - granted - remaining - usage description: >- The balances behind the totals. Rollovers are not listed; the totals minus these balances is what rollovers hold. required: - totals - breakdown - type: 'null' description: >- The balance now, on the first page of a listing with no custom_range or recorded_range; null otherwise and for an unlimited balance. required: - list - has_more - next_cursor - entity_id - coverage - current examples: - list: - id: hist_Y2hhbmdlXzM occurred_at: 1761609600000 recorded_at: 1761609600412 effective_at: 1761609600000 feature_id: messages entity_id: null why: type: reset actor: type: reset id: null before: granted: 1000 remaining: 120 usage: 880 after: granted: 1000 remaining: 1000 usage: 0 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 plan_id: pro before: granted: 1000 remaining: 120 usage: 880 after: granted: 1000 remaining: 1000 usage: 0 - id: hist_Z3JvdXBfMg occurred_at: 1761580800000 recorded_at: 1761580801207 effective_at: null feature_id: messages entity_id: null why: type: track_group count: 214 amount: 380 occurred_from: 1761523200000 occurred_to: 1761580800000 recorded_from: 1761523200530 recorded_to: 1761580801207 deductions: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null value: 380 approximate: null actor: type: secret_key id: key_123 before: granted: 1000 remaining: 500 usage: 500 after: granted: 1000 remaining: 120 usage: 880 breakdown: null - id: hist_cGxhbl8x occurred_at: 1761436800000 recorded_at: 1761436800310 effective_at: null feature_id: messages entity_id: null why: type: plan_change action: upgrade from_plan_ids: - free to_plan_ids: - pro actor: type: secret_key id: key_123 before: granted: 100 remaining: 0 usage: 100 after: granted: 1000 remaining: 900 usage: 100 breakdown: - balance_id: cus_ent_2AbQmZ0oFree11a9Neecl2a2Gc5 plan_id: free before: granted: 100 remaining: 0 usage: 100 after: null - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 plan_id: pro before: null after: granted: 1000 remaining: 900 usage: 100 has_more: true next_cursor: eyJ2IjowLCJ0IjoxNzYxNDM2ODAwMzEwfQ entity_id: null coverage: recording: true since: 1759300000000 current: totals: granted: 1000 remaining: 960 usage: 40 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 960 usage: 40 example: list: - id: hist_Y2hhbmdlXzM occurred_at: 1761609600000 recorded_at: 1761609600412 effective_at: 1761609600000 feature_id: messages entity_id: null why: type: reset actor: type: reset id: null before: granted: 1000 remaining: 120 usage: 880 after: granted: 1000 remaining: 1000 usage: 0 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 plan_id: pro before: granted: 1000 remaining: 120 usage: 880 after: granted: 1000 remaining: 1000 usage: 0 - id: hist_Z3JvdXBfMg occurred_at: 1761580800000 recorded_at: 1761580801207 effective_at: null feature_id: messages entity_id: null why: type: track_group count: 214 amount: 380 occurred_from: 1761523200000 occurred_to: 1761580800000 recorded_from: 1761523200530 recorded_to: 1761580801207 deductions: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null value: 380 approximate: null actor: type: secret_key id: key_123 before: granted: 1000 remaining: 500 usage: 500 after: granted: 1000 remaining: 120 usage: 880 breakdown: null - id: hist_cGxhbl8x occurred_at: 1761436800000 recorded_at: 1761436800310 effective_at: null feature_id: messages entity_id: null why: type: plan_change action: upgrade from_plan_ids: - free to_plan_ids: - pro actor: type: secret_key id: key_123 before: granted: 100 remaining: 0 usage: 100 after: granted: 1000 remaining: 900 usage: 100 breakdown: - balance_id: cus_ent_2AbQmZ0oFree11a9Neecl2a2Gc5 plan_id: free before: granted: 100 remaining: 0 usage: 100 after: null - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 plan_id: pro before: null after: granted: 1000 remaining: 900 usage: 100 has_more: true next_cursor: eyJ2IjowLCJ0IjoxNzYxNDM2ODAwMzEwfQ entity_id: null coverage: recording: true since: 1759300000000 current: totals: granted: 1000 remaining: 960 usage: 40 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 960 usage: 40 x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.listLedger({ customerId: "cus_123", featureId: "messages", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.list_ledger( customer_id="cus_123", feature_id="messages", limit=50, start_cursor="", tracks="grouped", ) components: securitySchemes: secretKey: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.