list_credit_balances
Retrieve customer credit balances across currencies to view available, reserved, and used amounts for transaction-based credits in Paddle Billing.
Instructions
This tool will list credit balances in each currency for a customer.
Credit balances are created automatically by Paddle when a customer takes an action that results in Paddle creating a credit for a customer, like making prorated changes to a subscription. These are transaction credits, not promotional credits like from discounts.
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.
A credit balance can only be used for transactions in the same currency.
Adding to a credit balance directly isn't possible. Create a credit adjustment with the create_adjustment tool to reduce the amount due to pay for a transaction instead.
Filter credit balances by currencyCode as needed. Amounts are in the smallest currency unit (e.g., cents).
The response isn't paginated. An empty array is returned if a customer has no credit balances.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customerId | Yes | Paddle ID of the customer. | |
| currencyCode | No | Return entities that match the currency code. Use a comma-separated list to specify multiple currency codes. |
Implementation Reference
- src/functions.ts:247-258 (handler)The handler function that executes the core logic of the list_credit_balances tool by calling the Paddle SDK's customers.getCreditBalance method.
export const listCreditBalances = async ( paddle: Paddle, params: z.infer<typeof Parameters.listCreditBalancesParameters>, ) => { try { const { customerId, ...queryParams } = params; const result = await paddle.customers.getCreditBalance(customerId, queryParams); return result; } catch (error) { return error; } }; - src/tools.ts:504-515 (schema)The tool schema definition, including method name, description, Zod parameters schema reference, and required permissions/actions.
{ method: "list_credit_balances", name: "List credit balances for a customer", description: prompts.listCreditBalancesPrompt, parameters: params.listCreditBalancesParameters, actions: { customers: { read: true, list: true, }, }, }, - src/api.ts:28-28 (registration)Registration of the listCreditBalances handler in the central toolMap used by PaddleAPI to dispatch tool calls.
[TOOL_METHODS.LIST_CREDIT_BALANCES]: funcs.listCreditBalances, - src/constants.ts:20-20 (helper)Constant definition for the tool method name string used across the codebase.
LIST_CREDIT_BALANCES: "list_credit_balances",