List balance changes for a period

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

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/balance-changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/balance-changes")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "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"
    }
  ],
  "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
    }
  },
  "hasMore": false,
  "nextCursor": "BalanceChange:019542f5-b3e7-1d02-0000-000000000003",
  "totalCount": 42
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Periodic Statements

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.

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.

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 separately, 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.

GET

internal-accounts

{id}

balance-changes

List balance changes for a period

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

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/balance-changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/balance-changes")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "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"
    }
  ],
  "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
    }
  },
  "hasMore": false,
  "nextCursor": "BalanceChange:019542f5-b3e7-1d02-0000-000000000003",
  "totalCount": 42
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

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

Query Parameters

startDate

string<date-time>

required

Start of the window, inclusive, in ISO 8601 format. Must carry a timezone, either Z for UTC or an offset.

endDate

string<date-time>

required

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.

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

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

startDate

string<date-time>

required

Start of the window, inclusive

Example:

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

endDate

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"

totalCount

integer

Number of balance changes in the window, across all pages

Example:

42

Using the API

API documentation

List balance changes for a period

Authorizations

Path Parameters

Query Parameters

Response