Get the net balance of a customer

Retrieve the combined current balance across any grouping of credits and commits for a customer in a single API call.

• Display real-time available balance to customers in billing dashboards
• Build finance dashboards showing credit utilization across customer segments
• Validate expected vs. actual balance during billing reconciliation

Key response fields:

• balance: The combined net balance available to use at this moment across all matching commits and credits
• credit_type_id: The credit type (fiat or custom pricing unit) the balance is denominated in

Filtering options:

Balance filters allow you to scope the calculation to specific subsets of commits and credits. When using multiple filter objects, they are OR’d together — if a commit or credit matches any filter, it’s included in the net balance. Within a single filter object, all specified conditions are AND’d together.

• Balance types: Include any combination of PREPAID_COMMIT, POSTPAID_COMMIT, and CREDIT (e.g., ["PREPAID_COMMIT", "CREDIT"] to exclude postpaid commits). If not specified, all balance types are included.
• Specific IDs: Target exact commit or credit IDs for precise balance queries
• Custom fields: Filter by custom field key-value pairs; when multiple pairs are provided, commits must match all of them

Example: To get the balance of all free-trial credits OR all signup-promotion commits, you’d pass two filter objects — one filtering for CREDIT with custom field campaign: free-trial, and another filtering for PREPAID_COMMIT with custom field campaign: signup-promotion.

Usage guidelines:

• Balance ledger details: Use the listBalances endpoint instead to understand detailed ledger drawdowns for each individual balance
• Draft invoice handling: Use invoice_inclusion_mode to control whether pending draft invoice deductions are included (FINALIZED_AND_DRAFT, the default) or excluded (FINALIZED) from the balance calculation
• Account hierarchies: When querying a child customer, shared commits from parent contracts are not included — query the parent customer directly to see shared commit balances
• Negative balances: Manual ledger entries can cause negative segment balances; these are treated as zero when calculating the net balance
• Credit types: If credit_type_id is not specified, the balance defaults to USD (cents)