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"
    }
  ],
  "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
}

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

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

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 --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"
    }
  ],
  "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
}

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

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

from

string<date-time>

required

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

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

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

Using the API

API documentation

List balance changes for a period

Authorizations

Path Parameters

Query Parameters

Response