List Balances

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

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

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.balances.list(
    customer_id="cus_123",
    limit=50,
    start_cursor="",
    statuses=[
        "expired",
    ],
)

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
}

POST

balances.list

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

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

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.balances.list(
    customer_id="cus_123",
    limit=50,
    start_cursor="",
    statuses=[
        "expired",
    ],
)

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
}

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

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

Only return balances for this feature, or for any of these features.

Response

200 - application/json

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.

Billing

Balances

Customers

Invoices

Authorization

Analytics

Logs

Entities

Accounts

Plans

Features

Rewards & Referrals

Webhooks

Webhook Events

Platform (Beta)

Body Parameters

Response

Authorizations

Headers

Body

Response