Docs

List credit balances for a customer

Returns a list of credit balances for each currency for a customer.

GET /customers/{customer_id}/credit-balances

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.

Requires customer.read permission.

Path parameters

customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$

Query parameters

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

Response (200)

dataarrayrequired
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of the customer that this credit balance is for, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
currency_codestringrequired
Three-letter ISO 4217 currency code for this credit balance.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
balanceobjectrequired
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.
availablestringrequired
Example: 200
Total amount of credit available to use.
reservedstringrequired
Example: 400
Total amount of credit temporarily reserved for billed transactions.
usedstringrequired
Example: 600
Total amount of credit used.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Response
{
  "data": [
    {
      "customer_id": "ctm_01gw9m680k848184fpttwr0b7z",
      "currency_code": "USD",
      "balance": {
        "available": "550",
        "reserved": "900",
        "used": "1300"
      }
    }
  ],
  "meta": {
    "request_id": "32cf1966-ed49-47d6-a76a-a9b8f7843245"
  }
}

Was this page helpful?