Stripe: Create a customer balance transaction

Stripe customers.postCustomersCustomerBalanceTransactions: arguments, response, policy and SDK examples.

Operation stripe.postcustomerscustomerbalancetransactions

Provider route: POST /v1/customers/{customer}/balance_transactions. 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["customers"]["postCustomersCustomerBalanceTransactions"]>[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.customers.postCustomersCustomerBalanceTransactions(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.customers.post_customers_customer_balance_transactions(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
`$`	object	Root	Additional keys: not allowed
`path`	object	Required within parent	Additional keys: not allowed
`path.customer`	string	Required within parent	Maximum length: 5000
`headers`	object	Optional	Additional keys: not allowed
`headers.Idempotency-Key`	string	Optional	Minimum length: 1 Maximum length: 255
`body`	object	Required within parent	Additional keys: not allowed
`body.amount`	integer	Required within parent	The integer amount in cents (or local equivalent) to apply to the customer’s credit balance.
`body.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). Specifies the [`invoice_credit_balance`](https://docs.stripe.com/api/customers/object#customer_object-invoice_credit_balance) that this transaction will apply to. If the customer’s `currency` is not set, it will be updated to this value. Format: currency
`body.description`	string	Optional	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 350
`body.expand`	array	Optional	Specifies which fields in the response should be expanded.
`body.expand[]`	string	Each item	Maximum length: 5000
`body.metadata`	JSON	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
`body.metadata (anyOf 1)`	object	Alternative	Additional keys: see wildcard field
`body.metadata (anyOf 1).*`	string	Additional keys
`body.metadata (anyOf 2)`	string	Alternative	One of:

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 Create a customer balance transaction — response body

Referenced models: Create a customer balance transaction — response body

Schemas

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

Create a customer balance transaction — response body

Field	Type	Presence	Description and constraints
`$`	object	Root	Each customer has a [Balance](https://docs.stripe.com/api/customers/object#customer_object-balance) value, which denotes a debit or credit that's automatically applied to their next invoice upon finalization. You may modify the value directly by using the [update customer API](https://docs.stripe.com/api/customers/update), or by creating a Customer Balance Transaction, which increments or decrements the customer's `balance` by the specified `amount`. Related guide: [Customer balance](https://docs.stripe.com/billing/customer/balance)
`amount`	JSON	Required within parent
`amount (anyOf 1)`	integer	Alternative	The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's `balance`.
`amount (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`checkout_session`	JSON	Optional
`checkout_session (anyOf 1)`	JSON	Alternative	The ID of the checkout session (if any) that created the transaction.
`checkout_session (anyOf 1) (anyOf 1)`	string	Alternative	Maximum length: 5000
`checkout_session (anyOf 1) (anyOf 2)`	Model	Alternative	Expand Create a Checkout Session — response body
`checkout_session (anyOf 2)`	null	Alternative
`created`	JSON	Required within parent
`created (anyOf 1)`	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
`created (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`credit_note`	JSON	Optional
`credit_note (anyOf 1)`	JSON	Alternative	The ID of the credit note (if any) related to the transaction.
`credit_note (anyOf 1) (anyOf 1)`	string	Alternative	Maximum length: 5000
`credit_note (anyOf 1) (anyOf 2)`	Model	Alternative	Expand Void a credit note — response body
`credit_note (anyOf 2)`	null	Alternative
`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). Format: currency
`customer`	JSON	Required within parent	The ID of the customer the transaction belongs to.
`customer (anyOf 1)`	string	Alternative	Maximum length: 5000
`customer (anyOf 2)`	Model	Alternative	Expand Create a customer — response body
`customer_account`	JSON	Optional
`customer_account (anyOf 1)`	string	Alternative	The ID of an Account representing a customer that the transaction belongs to. Maximum length: 5000
`customer_account (anyOf 2)`	null	Alternative
`description`	JSON	Optional
`description (anyOf 1)`	string	Alternative	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
`description (anyOf 2)`	null	Alternative
`ending_balance`	JSON	Required within parent
`ending_balance (anyOf 1)`	integer	Alternative	The customer's `balance` after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.
`ending_balance (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`id`	string	Required within parent	Unique identifier for the object. Maximum length: 5000
`invoice`	JSON	Optional
`invoice (anyOf 1)`	JSON	Alternative	The ID of the invoice (if any) related to the transaction.
`invoice (anyOf 1) (anyOf 1)`	string	Alternative	Maximum length: 5000
`invoice (anyOf 1) (anyOf 2)`	Model	Alternative	Expand Pay an invoice — response body
`invoice (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`.
`metadata`	JSON	Optional
`metadata (anyOf 1)`	object	Alternative	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
`metadata (anyOf 1).*`	string	Additional keys	Maximum length: 500
`metadata (anyOf 2)`	null	Alternative
`object`	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer_balance_transaction
`type`	string	Required within parent	Transaction type: `adjustment`, `applied_to_invoice`, `credit_note`, `initial`, `invoice_overpaid`, `invoice_too_large`, `invoice_too_small`, `unspent_receiver_credit`, `unapplied_from_invoice`, `checkout_session_subscription_payment`, or `checkout_session_subscription_payment_canceled`. See the [Customer Balance page](https://docs.stripe.com/billing/customer/balance#types) to learn more about transaction types. Known values: adjustment, applied_to_invoice, checkout_session_subscription_payment, checkout_session_subscription_payment_canceled, credit_note, initial, invoice_overpaid, invoice_too_large, invoice_too_small, migration, unapplied_from_invoice, unspent_receiver_credit

Referenced models: Create a Checkout Session — response body, Void a credit note — response body, Create a customer — response body, Pay an invoice — response body

Create a Checkout Session — response body — wallet options value link

Field	Type	Presence	Description and constraints
`$`	object	Root
`link`	Model	Optional	Expand Create a Checkout Session — response body — wallet options value link link

Referenced models: Create a Checkout Session — response body — wallet options value link link

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

Cancel a refund — response body — presentment details

Field	Type	Presence	Description and constraints
`$`	object	Root
`presentment_amount`	JSON	Required within parent
`presentment_amount (anyOf 1)`	integer	Alternative	Amount intended to be collected by this payment, denominated in `presentment_currency`.
`presentment_amount (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`presentment_currency`	string	Required within parent	Currency presented to the customer during payment. Maximum length: 5000

Create a payment link — response body — custom text

Field	Type	Presence	Description and constraints
`$`	object	Root
`after_submit`	JSON	Optional
`after_submit (anyOf 1)`	JSON	Alternative	Custom text that should be displayed after the payment confirmation button.
`after_submit (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Create a payment link — response body — custom text submit value message
`after_submit (anyOf 2)`	null	Alternative
`shipping_address`	JSON	Optional
`shipping_address (anyOf 1)`	JSON	Alternative	Custom text that should be displayed alongside shipping address collection.
`shipping_address (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Create a payment link — response body — custom text submit value message
`shipping_address (anyOf 2)`	null	Alternative
`submit`	JSON	Optional
`submit (anyOf 1)`	JSON	Alternative	Custom text that should be displayed alongside the payment confirmation button.
`submit (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Create a payment link — response body — custom text submit value message
`submit (anyOf 2)`	null	Alternative
`terms_of_service_acceptance`	JSON	Optional
`terms_of_service_acceptance (anyOf 1)`	JSON	Alternative	Custom text that should be displayed in place of the default terms of service agreement text.
`terms_of_service_acceptance (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Create a payment link — response body — custom text submit value message
`terms_of_service_acceptance (anyOf 2)`	null	Alternative

Referenced models: Create a payment link — response body — custom text submit value message

Cancel a Setup Intent — response body — payment method configuration details value id, parent

Field	Type	Presence	Description and constraints
`$`	object	Root
`id`	string	Required within parent	ID of the payment method configuration used. Maximum length: 5000
`parent`	JSON	Optional
`parent (anyOf 1)`	string	Alternative	ID of the parent payment method configuration used. Maximum length: 5000
`parent (anyOf 2)`	null	Alternative

Policy, approvals and errors

SDK function policy ID: stripe.postcustomerscustomerbalancetransactions. Catalog operation: PostCustomersCustomerBalanceTransactions. 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

Report an issue with this page