Stripe: Retrieve the credit balance summary for a customer

← Billing operations · Get started

Operation stripe.getbillingcreditbalancesummary

Provider route: GET /v1/billing/credit_balance_summary. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["billing"]["getBillingCreditBalanceSummary"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.billing.getBillingCreditBalanceSummary(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.billing.get_billing_credit_balance_summary(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.customer	string	Optional	Maximum length: 5000
query.customer_account	string	Optional	Maximum length: 5000
query.expand	array	Optional
query.expand[]	string	Each item	Maximum length: 5000
query.filter	object	Required within parent
query.filter.applicability_scope	object	Optional
query.filter.applicability_scope.price_type	string	Optional	One of: metered
query.filter.applicability_scope.prices	array	Optional
query.filter.applicability_scope.prices[]	object	Each item
query.filter.applicability_scope.prices[].id	string	Required within parent	Maximum length: 5000
query.filter.credit_grant	string	Optional	Maximum length: 5000
query.filter.type	string	Required within parent	One of: applicability_scope, credit_grant

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Retrieve the credit balance summary for a customer — response body

Referenced models: Retrieve the credit balance summary for a customer — response body

Schemas

702 more schemas are linked from the tables above, on the schema pages.

Retrieve the credit balance summary for a customer — response body

Field	Type	Presence	Description and constraints
$	object	Root	Indicates the billing credit balance for billing credits granted to a customer.
balances	array	Required within parent	The billing credit balances. One entry per credit grant currency. If a customer only has credit grants in a single currency, then this will have a single balance entry.
balances[]	Model	Each item	Expand Retrieve the credit balance summary for a customer — response body — balances item
customer	JSON	Required within parent	The customer the balance is for.
customer (anyOf 1)	string	Alternative	Maximum length: 5000
customer (anyOf 2)	Model	Alternative	Expand Create a customer — response body
customer (anyOf 3)	Model	Alternative	Expand Delete a customer — response body
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The account the balance is for. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: billing.credit_balance_summary

Referenced models: Retrieve the credit balance summary for a customer — response body — balances item, Create a customer — response body, Delete a customer — response body

Retrieve the credit balance summary for a customer — response body — balances item

Field	Type	Presence	Description and constraints
$	object	Root
available_balance	Model	Required within parent	Expand Void a credit grant — response body — amount
ledger_balance	Model	Required within parent	Expand Void a credit grant — response body — amount

Referenced models: Void a credit grant — response body — amount

Delete a customer — response body

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer

Void a credit grant — response body — amount

Field	Type	Presence	Description and constraints
$	object	Root
monetary	JSON	Optional
monetary (anyOf 1)	JSON	Alternative	The monetary amount.
monetary (anyOf 1) (anyOf 1)	Model	Alternative	Expand Void a credit grant — response body — amount monetary The monetary amount currency, value
monetary (anyOf 2)	null	Alternative
type	string	Required within parent	The type of this amount. We currently only support `monetary` billing credits. Known values: monetary

Referenced models: Void a credit grant — response body — amount monetary The monetary amount currency, value

Create a Location — response body — address

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	City, district, suburb, town, or village. Maximum length: 5000
city (anyOf 2)	null	Alternative
country	JSON	Optional
country (anyOf 1)	string	Alternative	Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
country (anyOf 2)	null	Alternative
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Address line 1, such as the street, PO Box, or company name. Maximum length: 5000
line1 (anyOf 2)	null	Alternative
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Address line 2, such as the apartment, suite, unit, or building. Maximum length: 5000
line2 (anyOf 2)	null	Alternative
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	ZIP or postal code. Maximum length: 5000
postal_code (anyOf 2)	null	Alternative
state	JSON	Optional
state (anyOf 1)	string	Alternative	State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). Maximum length: 5000
state (anyOf 2)	null	Alternative

Retrieve a cash balance — response body

Field	Type	Presence	Description and constraints
$	object	Root	A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.
available	JSON	Optional
available (anyOf 1)	object	Alternative	A hash of all cash balances available to this customer. You cannot delete a customer with any cash balances, even if the balance is 0. Amounts are represented in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal). Additional keys: see wildcard field
available (anyOf 1).*	JSON	Additional keys
available (anyOf 1).* (anyOf 1)	integer	Alternative
available (anyOf 1).* (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
available (anyOf 2)	null	Alternative
customer	string	Required within parent	The ID of the customer whose cash balance this object represents. Maximum length: 5000
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The ID of an Account representing a customer whose cash balance this object represents. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: cash_balance
settings	Model	Required within parent	Expand Retrieve a cash balance — response body — settings

Referenced models: Retrieve a cash balance — response body — settings

Create a customer — response body — tax

Field	Type	Presence	Description and constraints
$	object	Root
automatic_tax	string	Required within parent	Surfaces if automatic tax computation is possible given the current customer location information. Known values: failed, not_collecting, supported, unrecognized_location
ip_address	JSON	Optional
ip_address (anyOf 1)	string	Alternative	A recent IP address of the customer used for tax reporting and tax location inference. Maximum length: 5000
ip_address (anyOf 2)	null	Alternative
location	JSON	Optional
location (anyOf 1)	JSON	Alternative	The identified tax location of the customer.
location (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a customer — response body — tax / location / The identified tax location of the customer / source: billing address, ip address, payment method, shipping destination
location (anyOf 2)	null	Alternative
provider	string	Required within parent	The tax calculation provider used for location resolution. Defaults to `stripe` when not using a [third-party provider](/tax/third-party-apps). Known values: anrok, avalara, sphere, stripe

Referenced models: Create a customer — response body — tax / location / The identified tax location of the customer / source: billing address, ip address, payment method, shipping destination

Void a credit grant — response body — amount monetary The monetary amount currency, value

Field	Type	Presence	Description and constraints
$	object	Root
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Maximum length: 5000
value	JSON	Required within parent
value (anyOf 1)	integer	Alternative	A positive integer representing the amount.
value (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Pay an invoice — response body — custom fields Custom fields displayed on the invoice item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Required within parent	The name of the custom field. Maximum length: 5000
value	string	Required within parent	The value of the custom field. Maximum length: 5000

Policy, approvals and errors

SDK function policy ID: stripe.getbillingcreditbalancesummary. Catalog operation: GetBillingCreditBalanceSummary. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source