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 Dictionary
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, 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

objectstring

checkout_sessionnullable stringExpandable

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.

metadataDictionary
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

Server-side language

StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var options = new CustomerBalanceTransactionCreateOptions
{
    Amount = -500,
    Currency = "usd",
};
var service = new CustomerBalanceTransactionService();
CustomerBalanceTransaction customerBalanceTransaction = service.Create(
    "cus_NcjdgdwZyI9Rj7",
    options);

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.

metadataDictionary
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

Server-side language

StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var options = new CustomerBalanceTransactionUpdateOptions
{
    Metadata = new Dictionary<string, string> { { "order_id", "6735" } },
};
var service = new CustomerBalanceTransactionService();
CustomerBalanceTransaction customerBalanceTransaction = service.Update(
    "cus_NcjdgdwZyI9Rj7",
    "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI",
    options);

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

Server-side language

StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var service = new CustomerBalanceTransactionService();
CustomerBalanceTransaction customerBalanceTransaction = service.Get(
    "cus_NcjdgdwZyI9Rj7",
    "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI");

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

Server-side language

StripeConfiguration.ApiKey = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var options = new CustomerBalanceTransactionListOptions { Limit = 3 };
var service = new CustomerBalanceTransactionService();
StripeList<CustomerBalanceTransaction> customerBalanceTransactions = service.List(
    "cus_NcjdgdwZyI9Rj7",
    options);

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"
    }
  ]
}

The Customer Balance Transaction object

Attributes

idstring

amountinteger

currencyenum

customerstringExpandable

descriptionnullable string

ending_balanceinteger

metadatanullable Dictionary

typeenum

More attributesExpand all

objectstring

checkout_sessionnullable stringExpandable

createdtimestamp

credit_notenullable stringExpandable

invoicenullable stringExpandable

livemodeboolean

Create a customer balance transaction

Parameters

amountintegerRequired

currencyenumRequired

descriptionstring

metadataDictionary

Returns

Update a customer credit balance transaction

Parameters

descriptionstring

metadataDictionary

Returns

Retrieve a customer balance transaction

Parameters

Returns

List customer balance transactions

Parameters

More parametersExpand all

ending_beforestring

limitinteger

starting_afterstring

Returns

More attributes

More parameters