The Customer Balance Transaction object

Attributes

• id string Unique identifier for the object.
• 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.
• currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
• customer string Expandable The ID of the customer the transaction belongs to.
• customer _ account nullable string The ID of an Account representing a customer that the transaction belongs to.
• description nullable 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.
• metadata nullable map 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.
• type enum 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. Possible enum values adjustment An explicitly created adjustment transaction to debit or credit the credit balance. applied_to_invoice Traces the application of credit against a linked Invoice. checkout_session_subscription_payment Traces the customer balance applied to an Invoice to be created for the linked Checkout Session. checkout_session_subscription_payment_canceled Traces the reversal of an applied balance by the linked Checkout Session. Paired with an earlier ‘checkout_session_subscription_payment‘ transaction. credit_note Traces the creation of credit to a Credit Note and its associated Invoice. initial The starting value of the customer’s credit balance. invoice_overpaid Credits to the credit balance when an invoice receives payments exceeding the amount due. invoice_too_large Debits to the credit balance when the amount due on an invoice is greater than Stripe’s maximum chargeable amount and the customer does not have a cash balance. invoice_too_small Debits to the credit balance when the amount due on an invoice is less than Stripe’s minimum chargeable amount and the customer does not have a cash balance. migration Funds migrated from the legacy customer credit balance. Show 2 more

More attributes

• object string, value is "customer_balance_transaction"
• checkout _ session nullable string Expandable
• created timestamp
• credit _ note nullable string Expandable
• invoice nullable string Expandable
• livemode boolean

The Customer Balance Transaction object

{ "id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI", "object": "customer_balance_transaction", "amount": -500, "created": 1680216086, "credit_note": null, "currency": "usd", "customer": "cus_NcjdgdwZyI9Rj7", "description": null, "ending_balance": -500, "invoice": null, "livemode": false, "metadata": {}, "type": "adjustment"}

Create a customer balance transaction

POST / v1 / customers /:id / balance_transactions

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

Parameters

• amount integer Required The integer amount in the smallest currency unit to apply to the customer’s credit balance.
• currency enum Required 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. The maximum length is 350 characters.
• metadata map 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.

Returns

Returns a customer balance transaction object if the call succeeded.

Response

{ "id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI", "object": "customer_balance_transaction", "amount": -500, "created": 1680216086, "credit_note": null, "currency": "usd", "customer": "cus_NcjdgdwZyI9Rj7", "description": null, "ending_balance": -500, "invoice": null, "livemode": false, "metadata": {}, "type": "adjustment"}

Update a customer credit balance transaction

POST / v1 / customers /:id / balance_transactions /:id

Most credit balance transaction fields are immutable, but you may update its description and metadata.

Parameters

• description string An arbitrary string attached to the object. Often useful for displaying to users. The maximum length is 350 characters.
• metadata map 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.

Returns

Returns a customer balance transaction object if the call succeeded.

Response

{ "id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI", "object": "customer_balance_transaction", "amount": -500, "created": 1680216086, "credit_note": null, "currency": "usd", "customer": "cus_NcjdgdwZyI9Rj7", "description": null, "ending_balance": -500, "invoice": null, "livemode": false, "metadata": { "order_id": "6735" }, "type": "adjustment"}