List Subscription Balance Entries

Retrieve a list of Subscription Balance Entry resources to view a timeline of all changes to a Subscription balance by a user. Currently, only credits can modify a Subscription balance.

For details on how to query endpoints using the available parameters, see Query Parameters.

Endpoint:

GET /subscriptions/{subscription_id}/subscription_balance_entries

Security:

BasicAuth

Path parameters:

• subscription_id (string, required)
  The ID of the Subscription.
  Example: "subscription_cAqNtRY2oKTJWbjMSDgrk"

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.

• amount (integer)
  Filter by an amount equal to the given value.
  Example: 100

• amount.gt (integer)
  Filter by an amount greater than.
  Example: 100

• amount.gte (integer)
  Filter by an amount greater than or equal.
  Example: 100

• amount.lt (integer)
  Filter by an amount less than.
  Example: 100

• amount.lte (integer)
  Filter by an amount less than or equal.
  Example: 100

• 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 number of items to return.
  Example: 10

• sort (string)
  Specify the key to be used for sorting the collection. Acceptable values are:

• updated_at

  • created_at

• 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.subscription_balance_entries (array)

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

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

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

• _embedded.subscription_balance_entries.amount (integer)
  The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).
  Example: 5000

• _embedded.subscription_balance_entries.currency (string)
  ISO 4217 3-letter currency code. Currently, the only currency supported is USD.
  Enum: "USD"

• _embedded.subscription_balance_entries.description (string)
  Describes the circumstances for the subscription credit.

• _embedded.subscription_balance_entries.subscription_id (string)
  The Subscription that was credited.

• _embedded.subscription_balance_entries.type (string)
  The value of this field will always be CREDIT.

• _embedded.subscription_balance_entries.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)

• _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 404 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.