Customer Balance

    How to use the customer balance ledger

    Every customer in Stripe Billing has a ledger against which you can issue credit and debit adjustments. These adjustments sum up to a balance on the customer which can be applied to future invoices. A customer’s balance could be a credit (meaning you owe them money) or a debit (meaning they owe you money).

    Because the customer balance is computed from a ledger—an immutable list of debit and credit transactions—it provides an audit trail of transactions for the customer. These Customer Balance Transactions can contain useful metadata, which object created the balance adjustment (such as a Credit Note), or which object used the balance (such as applying it to an Invoice).

    Examples

    Customer Balances are used in many ways, some common use cases include:

    • When the amount due on an invoice is less than the minimum chargeable amount the invoice is marked as paid and the amount owed moved to the customer balance as a debit.
    • Rather than refunding money back to the customer’s payment method, issue a Credit Note to create a customer balance credit that you can use to reduce the amount due on their next invoice.

    Good to know

    • The customer balance is applied to the amount due on their next invoice.
    • You cannot choose a specific invoice to apply the balance to.
    • You cannot choose to not apply the balance.
    • The customer balance is stored in the Customer’s currency.

    Debits and Credits

    Negative values are treated as a credit (a reduction in the amount owed by the customer) which can be applied to the customer’s next invoice.

    Positive values are treated as a debit (an increase in the amount owed by the customer to you) which can be applied to the customer’s next invoice.

    Understanding Transactions

    All modifications to the customer balance are recorded as immutable Customer Balance Transactions. Once created, you may only update its description or metadata–you cannot edit other properties or delete a transaction. You can only undo it by creating a corresponding, reversing transaction. For instance, if you credit the customer $10 you would have to debit the customer $10 in a new transaction, each canceling the other one out.

    Transaction Types

    All Customer Balance Transactions created with the API or in the Dashboard have a type value of adjustment, representing a debit or credit manually created by you for the customer.

    However, for auditing purposes, the type property has many more possible values to represent the creation source and reason for the transaction. The following table outlines and describes each of these type values.

    Type Description
    adjustment Manually created adjustment transaction, either debit or credit. The only type of transaction that can be created via API integrations & the Dashboard.
    applied_to_invoice Traces the use of the customer balance against a linked Invoice.
    credit_note Traces the creation of a credit adjustment to a Credit Note (and it’s associated Invoice).
    invoice_too_small When the amount due on an invoice is less than the minimum chargeable amount (the processing fee) the invoice is debited to the customer balance and will be added to the amount due of the next issued invoice.
    invoice_too_large When the amount due on an invoice is too large the amount due is added to the Customer Balance.
    unspent_receiver_credit When unspent funds in receiver sources are not fully charged after 60 days, Stripe automatically charges them on your behalf and credits your balance. When this happens, Stripe also creates a corresponding credit transaction to the customer’s balance labeled as “Funds sent by customer” on the customer detail page in the Dashboard.
    initial Represents the starting value of the customer balance ledger where a customer is created via the API with a non-zero balance.

    Modifying the Customer Balance

    You can modify a customer’s balance through the Dashboard by creating a new Customer Balance Transaction adjustment from the Customer’s detail page.

    Scroll down to find the Customer balance panel, and click the Add balance adjustment button to display the Customer balance adjustment modal.

    From here you can set information about the adjustment, such as the Adjustment type (credit or debit), as well as a Currency (only available if the customer does not yet have a currency set), Amount, and an internal note (visible to Dashboard users, but not the customer).

    Adding a new Customer Balance Transaction adjustment

    API

    Create adjustments via the Customer Balance API, as shown in the following code example.

    curl https://api.stripe.com/v1/customers/cus_4fdAW5ftNQow1a/balance_transactions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d amount=-500 \
      -d currency=usd
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    Stripe::Customer.create_balance_transaction(
      'cus_4fdAW5ftNQow1a',
      {
        amount: -500,
        currency: 'usd',
      }
    )
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    stripe.Customer.create_balance_transaction(
      'cus_4fdAW5ftNQow1a',
      amount=-500,
      currency='usd',
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    \Stripe\Customer::createBalanceTransaction(
      'cus_4fdAW5ftNQow1a',
      [
        'amount' => -500,
        'currency' => 'usd',
      ]
    );
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Customer customer = Customer.retrieve("cus_4fdAW5ftNQow1a");
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("amount", -500);
    params.put("currency", "usd");
    customer.balanceTransactions().create(params);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    (async () => {
      const txn = await stripe.customers.createBalanceTransaction(
        'cus_4fdAW5ftNQow1a',
        {
          amount: -500,
          currency: 'usd',
        }
      );
    })();
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.CustomerBalanceTransactionParams{
      Amount: stripe.Int64(-500),
      Currency: stripe.String(string(stripe.CurrencyUSD)),
      Customer: stripe.String("cus_4fdAW5ftNQow1a"),
    }
    txn, err := customerbalancetransaction.New(params)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    var options = new CustomerBalanceTransactionCreateOptions {
        Amount = -500,
        Currency = "usd",
    };
    var service = new CustomerBalanceTransactionService();
    var transaction = service.Create(options);
    

    Customer Balance Transaction history

    Audit a Customer’s balance adjustments in the Dashboard by navigating to a Customer’s detail page and scrolling to the Customer balance panel.

    The Customer balance panel displays the current value of the customer balance, as well as the immutable transaction history used to calculate that value. Each transaction line displays information relevant to the transaction type, such as a link to the invoice that applied the customer’s balance, or the credit note which credited the customer’s balance.

    Viewing the Customer Balance Transaction history

    API

    Use the Customer Balance List API to retrieve a list of all transactions for a Customer.

    curl https://api.stripe.com/v1/customers/cus_4fdAW5ftNQow1a/balance_transactions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    Stripe::Customer.list_balance_transactions('cus_4fdAW5ftNQow1a')
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    stripe.Customer.list_balance_transactions('cus_4fdAW5ftNQow1a')
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    \Stripe\Customer::allBalanceTransactions('cus_4fdAW5ftNQow1a');
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Customer.retrieve("cus_FGaJuErtd0bNyK").balanceTransactions();
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    (async () => {
      const txns = stripe.customers.listBalanceTransactions('cus_4fdAW5ftNQow1a');
    })();
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.CustomerBalanceTransactionListParams{
      Customer: stripe.String("cus_4fdAW5ftNQow1a"),
    }
    i := customerbalancetransaction.List(params)
    for i.Next() {
      txn := i.CustomerBalanceTransaction()
    }
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    var options = new CustomerBalanceTransactionListOptions {};
    var service = new CustomerBalanceTransactionService();
    var transactions = service.List("cus_4fdAW5ftNQow1a", options);
    

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page