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.

POST /v1/balances.list

Typescript (SDK)

TypeScript

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.balances.list({
  customerId: "cus_123",
  statuses: [
    "expired",
  ],
});

200

{
  "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
}

Lists individual balances, one row per grant: plan balances, standalone balances from 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.

A page can hold fewer than limit rows (even zero) while has_more is true. Keep paginating until has_more is false.

Body Parameters

Response

200

{
  "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

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.4.0 · required

Body

application/json

customer_id · string

Only return rows for this customer. Omit to list across every customer.

entity_id · string

Only return rows for this entity. Requires customer_id.

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.

statuses · enum<string>[]

Statuses to include. Defaults to active. A balance is expired when its plan expired, or when a standalone balance passed its expires_at.

Minimum array length: 1

Available options: active, expired

plan_id · string | null

Only return balances from this plan. Pass null for standalone balances only (top-ups, balances.create, rollovers).

feature_id · string

Only return balances for this feature.

Response

200 - application/json

OK

list · object[] · required

Rows on this page.

Show child attributes

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.