List balance changes for a period

Every change to this account’s balance in a window, in the order the money moved, with the opening and closing balances for that window in the same response.

This is the statement feed. GET /transactions returns one row per transaction. This returns one row per change to the balance, and a transaction that moves the balance more than once produces more than one change: an ACH deposit and its later return are two, and a card purchase that clears in two parts is two. Each change’s transactionId names its transaction, so fetch it from GET /transactions/{transactionId} for the type, counterparty and merchant a statement line shows.

The identity to assert: openingBalance + Σ(data[].amount) == closingBalance, summed over every page. The opening and closing balances describe the window rather than the page, so they are the same on every page. Page until hasMore is false, then assert the identity before rendering a statement.

from and to are instants and the window is half-open: a change at exactly to belongs to the next window. Consecutive periods therefore tile with no gap and no overlap. For a monthly statement, pass the first instant of the month and the first instant of the following month, both in US Central time (America/Chicago). Grid records a statement as fetched only for a window that is exactly one such month.

A window whose card settlement has not closed is refused with 409 NOT_YET_AVAILABLE, because its figures could still change. Retry once it has settled.

Fees are inside the changes. A fee Grid charges comes out of the balance, so it is already in amount: inside a send’s change, or a change of its own for a withdrawal’s fee. Each change’s fee says how much of its amount was a fee, negative when charged and positive when refunded. To show a fee as its own statement line, split the change into amount - fee and fee. Never add fee on top of amount, or the identity stops holding. Card transactions carry no Grid fee.

Merchant, counterparty and rail detail live on the transaction; read them from GET /transactions.

GET /internal-accounts/{id}/balance-changes

List balance changes for a period

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/balance-changes \
  --header 'Authorization: Basic <encoded-value>'

200

{
  "data": [
    {
      "id": "BalanceChange:019542f5-b3e7-1d02-0000-000000000003",
      "amount": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "fee": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "effectiveAt": "2026-09-03T14:31:00Z",
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000004"
    }
  ],
  "periodStart": "2026-08-01T00:00:00-05:00",
  "periodEnd": "2026-09-01T00:00:00-05:00",
  "openingBalance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "closingBalance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "hasMore": false,
  "nextCursor": "BalanceChange:019542f5-b3e7-1d02-0000-000000000003",
  "countIsExact": true,
  "totalCount": 42
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

id · string · required

The id of the internal account to list balance changes for.

Query Parameters

from · string<date-time> · required

Start of the window, inclusive. Must include a timezone offset.

to · string<date-time> · required

End of the window, exclusive. Must include a timezone offset and must not be in the future.

limit · integer · default: 100

Maximum number of changes to return per page

Required range: 1 <= x <= 200

cursor · string

Cursor for pagination (returned from previous request)

Response

200

application/json

The balance changes in the window, with the balances that bound it

A window of balance changes with the balances that bound it. The opening and closing balances describe the whole window, not the page, so they are the same on every page, and the identity openingBalance + Σ(data[].amount) == closingBalance holds only once every page's data is summed.

data · object[] · required

Balance changes on this page, ordered by effectiveAt

Show child attributes

periodStart · string<date-time> · required

Start of the window, inclusive

Example:

"2026-08-01T00:00:00-05:00"

periodEnd · string<date-time> · required

End of the window, exclusive

Example:

"2026-09-01T00:00:00-05:00"

openingBalance · object · required

Show child attributes

closingBalance · object · required

Show child attributes

hasMore · boolean · required

Indicates if more changes are available beyond this page

Example:

false

nextCursor · string

Cursor to retrieve the next page of results (only present if hasMore is true)

Example:

"BalanceChange:019542f5-b3e7-1d02-0000-000000000003"

countIsExact · boolean

Whether totalCount is exact rather than capped

Example:

true

totalCount · integer

Number of balance changes in the window, across all pages

Example:

42