post/v1/customers/{customer}/balance_transactions

Create a customer balance transaction

Creates an immutable transaction that updates the customer’s credit balance.

Path parameters

Name	Description
customer*

Request body

Field	Type	Description
amount*	integer	The integer amount in cents (or local equivalent) to apply to the customer's credit balance.
currency*	string (currency)	Three-letter ISO currency code, in lowercase. Must be a supported currency. Specifies the `invoice_credit_balance` that this transaction will apply to. If the customer's `currency` is not set, it will be updated to this value.
description	string	An arbitrary string attached to the object. Often useful for displaying to users.
expand	array<string>	Specifies which fields in the response should be expanded.
metadata	object \| string	Set of key-value pairs 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`.

Response

Field	Type	Description
amount*	integer	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_session	string \| checkout.session	The ID of the checkout session (if any) that created the transaction.
created*	integer (unix-time)	Time at which the object was created. Measured in seconds since the Unix epoch.
credit_note	string \| credit_note	The ID of the credit note (if any) related to the transaction.
currency*	string (currency)	Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer*	string \| customer	The ID of the customer the transaction belongs to.
customer_account	string	The ID of an Account representing a customer that the transaction belongs to.
description	string	An arbitrary string attached to the object. Often useful for displaying to users.
ending_balance*	integer	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.
id*	string	Unique identifier for the object.
invoice	string \| invoice	The ID of the invoice (if any) related to the transaction.
livemode*	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadata	object	Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
object*	string	String representing the object's type. Objects of the same type share the same value.
type*	string	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 to learn more about transaction types.