Sample - Stripe API
POST/v1/customers/{customer}/balance_transactions

Create a customer balance transaction

Creates an immutable transaction that changes a customer's credit balance. Supply amount and currency, and optionally add a description or metadata to explain or categorize the adjustment.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 5 body fields
customerstringrequired
The unique identifier of the customer whose credit balance to update; the value must be no longer than 5,000 characters.

The customer credit balance transaction to create.

amountintegerrequired
The integer amount in **cents (or local equivalent)** to apply to the customer's credit balance.
currencystringrequired
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.
descriptionstringoptional
An arbitrary string attached to the object. Often useful for displaying to users.
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
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`.

2 status codes
200Returns the created customer balance transaction, including its amount, currency, customer, resulting `ending_balance`, creation time, and transaction type.
amountintegerrequired
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`.
checkout_sessionstringoptional
The ID of the checkout session (if any) that created the transaction.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
credit_notestringoptional
The ID of the credit note (if any) related to the transaction.
currencystringrequired
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).
customerstringrequired
The ID of the customer the transaction belongs to.
customer_accountstringoptional
The ID of an Account representing a customer that the transaction belongs to.
descriptionstringoptional
An arbitrary string attached to the object. Often useful for displaying to users.
ending_balanceintegerrequired
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.
idstringrequired
Unique identifier for the object.
invoicestringoptional
The ID of the invoice (if any) related to the transaction.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectoptional
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.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:customer_balance_transaction
typestringrequired
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.
Allowed:adjustmentapplied_to_invoicecheckout_session_subscription_paymentcheckout_session_subscription_payment_canceledcredit_noteinitialinvoice_overpaidinvoice_too_largeinvoice_too_smallmigrationunapplied_from_invoiceunspent_receiver_credit
defaultReturned when the API cannot create the transaction and provides an error object.
errorobjectrequired

Error handling

amount and currency are required. currency must be a supported lowercase three-letter ISO currency code, and description must not exceed 350 characters when provided.