Each customer has a 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, or by creating a Customer Balance Transaction, which increments or decrements the customer’s balance by the specified amount.
Related guide: Customer balance
Attributes
- idstring
Unique identifier for the object.
- amountinteger
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. - currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- customerstringExpandable
The ID of the customer the transaction belongs to.
- descriptionnullable string
An arbitrary string attached to the object. Often useful for displaying to users.
- ending_
balanceinteger The customer’s
balanceafter 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. - metadatanullable 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.
- typeenum
Transaction type:
adjustment,applied_,to_ invoice credit_,note initial,invoice_,overpaid invoice_,too_ large invoice_,too_ small unspent_, orreceiver_ credit unapplied_. See the Customer Balance page to learn more about transaction types.from_ invoice Possible enum valuesadjustmentAn explicitly created adjustment transaction to debit or credit the credit balance.
applied_to_ invoice Traces the application of credit against a linked Invoice.
credit_note Traces the creation of credit to a Credit Note and its associated Invoice.
initialThe 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.
migrationFunds migrated from the legacy customer credit balance.
unapplied_from_ invoice Traces the reversal of an applied credit balance from a linked Invoice. Paired with an earlier ‘applied_to_invoice’ transaction.
unspent_receiver_ credit Unspent funds in receiver Sources that got automatically charged and credited to the balance.
Show 2 more
More attributes
- objectstring
- createdtimestamp
- credit_
notenullable stringExpandable - invoicenullable stringExpandable
- livemodeboolean
{ "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"}Creates an immutable transaction that updates the customer’s credit balance.
Parameters
- amountintegerRequired
The integer amount in cents to apply to the customer’s credit balance.
- currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency. Specifies the
invoice_that this transaction will apply to. If the customer’scredit_ balance currencyis not set, it will be updated to this value. - descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users.
- metadataobject
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.
{ "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"}Most credit balance transaction fields are immutable, but you may update its description and metadata.
Parameters
- descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users.
- metadataobject
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.
{ "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"}Retrieves a specific customer balance transaction that updated the customer’s balances.
Parameters
No parameters.
Returns
Returns a customer balance transaction object if a valid identifier was provided.
{ "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"}