List Balance Entries

A Balance Entry reflects a change to an application's Balance due to a Transfer or a Balance Adjustment (i.e., "top-up").

You can use this endpoint to obtain a list of Balance Entry objects.

Endpoint:

GET /balances/{balance_id}/balance_entries

Security:

BasicAuth

Path parameters:

• balance_id (string, required)
  The ID of the Balance.

Header parameters:

• Finix-Version (string)
  Specify the API version of your request. For more details, see Versioning.
  Example: "2022-02-01"

Query parameters:

• after_cursor (string)
  Return every resource created after the cursor value.

• before_cursor (string)
  Return every resource created before the cursor value.

• created_at.gte (string)
  Filter where created_at is after the given date.
  Example: "2022-09-27T11:21:23"

• created_at.lte (string)
  Filter where created_at is before the given date.
  Example: "2026-09-27T11:21:23"

• limit (integer)
  The numbers of items to return.
  Example: 10

• tags.key (string)
  Filter by the tag's key. For more information, see Tags.
  Example: "card_type"

• tags.value (string)
  Filter by the tag's value. For more information, see Tags.
  Example: "business_card"

• updated_at.gte (string)
  Filter where updated_at is after the given date.
  Example: "2022-09-27T11:21:23"

• updated_at.lte (string)
  Filter where updated_at is before the given date.
  Example: "2026-09-27T11:21:23"

Response 200 fields (application/json):

• page (object)
  Details the page that's returned.

• page.limit (integer)
  The number of entries to return.

• page.next_cursor (string,null)
  The cursor to use for the next page of results.

• _embedded (object)

• _embedded.balances (array)

• _embedded.balances.id (string)
  The ID of the resource.

• _embedded.balances.created_at (string)
  Timestamp of when the object was created.

• _embedded.balances.updated_at (string)
  Timestamp of when the object was last updated.

• _embedded.balances.available_amount (integer)
  The amount of funds that are currently safe to use or withdraw.

This balance reflects settled funds minus any initiated outflows (such as payouts) that reduce availability immediately, even if they have not yet fully posted.

Funds from incoming transactions (such as top-ups) are not included until they are finalized.

Example:

If the posted balance is $1,000, a $500 payout is initiated, and a $600 top-up is pending, the available_amount is $500.

• _embedded.balances.currency (string)
  ISO 4217 3-letter currency code.
  Enum: "CAD", "USD"

• _embedded.balances.linked_to (string)
  The ID of the resource (e.g., an Application) that the Balance is linked to.

• _embedded.balances.linked_type (string)
  Specifies the type of resource identified in linked_to.
  Enum: "APPLICATION"

• _embedded.balances.pending_amount (integer)
  The projected balance after all in-flight transactions are finalized.

This amount includes the posted balance adjusted by pending incoming and outgoing transactions, regardless of whether those funds are currently available for use.

Example:

If the posted balance is $1,000, a $500 payout is pending, and a $600 top-up is pending, the pending_amount is $1,100.

• _embedded.balances.posted_amount (integer)
  The total balance derived only from finalized, settled transactions.

This amount represents the authoritative ledger balance and does not include any pending incoming or outgoing transactions.

Example:

If $1,000 has fully settled and no transactions have posted since, the posted_amount is $1,000, even if payouts or top-ups are currently in progress.

• _embedded.balances.tags (object,null)
  Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)

• _embedded.balances.type (string)
  The type of transactions stored/ledgered on the Balance.
  Enum: "DISBURSEMENT"

• _embedded.balances._links (object)
  An object containing link(s) relevant to the request. You can store these links for follow-up requests.

• _embedded.balances._links.self (object)

• _embedded.balances._links.self.href (string)
  The path to the new Balance resource.

• _links (object)

• _links.self (object)
  Link to the resource that was used in the request.

• _links.self.href (string)

• _links.next (object)
  Link to the next page of entries.

• _links.next.href (string)

Response 401 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 403 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 406 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 422 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.