List balance changes for a period
Changed onEvery 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.
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 its type, counterparty, merchant and rail.
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.
startDate and endDate are instants in any timezone, UTC included, and the window is half-open: a change at exactly endDate belongs to the next window. Consecutive windows therefore tile with no gap and no overlap.
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.
A fee is already inside a change's amount. For the fee itself, read fees on the change's transaction, counting each transaction once.
Request
- Base URLhttps://api.lightspark.com/grid/2025-10-13
- URLhttps://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/balance-changes
- AuthHTTP basic
Query parameters
Start of the window, inclusive, in ISO 8601 format. Must carry a timezone, either Z for UTC or an offset.
End of the window, exclusive, in ISO 8601 format. Must carry a timezone, either Z for UTC or an offset, and must not be in the future.
Maximum number of changes to return per page
Cursor for pagination: the nextCursor from the previous page, unchanged. Send it with the same account, startDate and endDate as that page. A cursor does not expire.
Response
The balance changes in the window, with the balances that bound it
Example response
{
"data": [
{
"id": "BalanceChange:019542f5-b3e7-1d02-0000-000000000003",
"transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
"amount": {
"amount": 12550,
"currency": {
"code": "USD",
"name": "United States Dollar",
"symbol": "$",
"decimals": 2
}
},
"effectiveAt": "2026-09-03T14:31:00Z"
}
],
"startDate": "2026-08-01T00:00:00-05:00",
"endDate": "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
}
},
"nextCursor": "BalanceChange:019542f5-b3e7-1d02-0000-000000000003",
"totalCount": 42
}Changes
- info
added the optional property
/to the response with the status - info
added the optional property
/to the response with the status
- info
- warning
added the new
PURCHASE_CARD_LIMIT_REACHEDenum value to theresponse property for the response status
- warning