Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

The Customer Balance Transaction object 

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 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.

  • 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_receiver_credit, or unapplied_from_invoice. 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.

    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.

    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

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 

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_credit_balance that this transaction will apply to. If the customer’s currency is 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.

POST /v1/customers/:id/balance_transactions
curl https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d amount=-500 \
  -d currency=usd
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 

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.

POST /v1/customers/:id/balance_transactions/:id
curl https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions/cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735
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"
}

Retrieve a customer balance transaction 

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.

GET /v1/customers/:id/balance_transactions/:id
curl https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions/cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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"
}

List customer balance transactions 

Returns a list of transactions that updated the customer’s balances.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit customer balance transactions, starting after item starting_after. Each entry in the array is a separate customer balance transaction object. If no more items are available, the resulting array will be empty.

GET /v1/customers/:id/balance_transactions
curl -G https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}