Paddle Billing
Search

List credit balances for a customer

Returns a list of credit balances for each currency for a customer. Each balance has three totals:

  • available: total available to use.
  • reserved: total temporarily reserved for billed transactions.
  • used: total amount of credit used.

Credit is added to the available total initially. When used, it moves to the used total.

The reserved total is used when a credit balance is applied to a transaction that's marked as billed, like when working with an issued invoice. It's not available for other transactions at this point, but isn't considered used until the transaction is completed. If a billed transaction is canceled, any reserved credit moves back to available.

Credit balances are created automatically by Paddle when you take an action that results in Paddle creating a credit for a customer, like making prorated changes to a subscription. An empty data array is returned where a customer has no credit balances.

The response is not paginated.

Path Parameters

customer_idstringrequired

Paddle ID of the customer entity to work with.

Query Parameters

currency_codearray[string]

Return entities that match the currency code. Use a comma-separated list to specify multiple currency codes.

Response

dataarray[object]

Represents a credit balance for a customer.

customer_idstring

Paddle ID of the customer that this credit balance is for, prefixed with ctm_.

currency_codestring

Three-letter ISO 4217 currency code for this credit balance.

balanceobject

Totals for this credit balance. Where a customer has more than one subscription in this currency with a credit balance, includes totals for all subscriptions.

metaobject

Information about this response.

request_idstring

Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.