# 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.