When a subscription is upgraded, Stripe will automatically calculate the prorated amount that the customer owes. For example, if a customer is moved from a $10.00/mo subscription price to a $100.00/mo subscription price in the middle of their billing cycle, they are owed a $5.00 credit for the first price and they owe $50.00 for the new price. This means that they owe a total of $45.00 for the subscription upgrade. This amount can be charged at the end of the billing cycle or immediately by creating an invoice.

When a subscription is downgraded or canceled, the customer may be owed a credit. If a customer moves from a $100.00/mo subscription price to a $10.00/mo subscription price in the middle of the billing cycle, they are owed $50.00 for the first price and owe $5.00 for the new price. A total of $45.00 is now owed to the customer for the subscription downgrade and that credit ends up being added to their credit balance to be applied to future invoices.

Some merchants may want to refund that credit amount directly to their customers' original method of payment. Today, this is not something that happens automatically and instead can be actioned by the merchant.

Refunding the Customers Credit Balance

• Retrieve the Customer's Credit Balance and/or sum pending invoice items
• Using the List Invoices API, pass the Subscription ID in the subscription parameter to view Invoices for that Subscription ID only
• You'll then need to expand the associated charge

Then, for each invoice:

• Locate the associated charge
• Create a refund for up to the amount of the customer's credit balance
• If the charge amount is smaller than the customer's credit balance, refund the full charge amount, and then subtract the full charge amount from the customer's credit balance to get the remaining balance to refund. For example: If the customer's credit balance = $100, and the latest subscription charge = $40, the remaining credit balance to refund = $60.
• Move to the next invoice in the list until the full credit has been refunded
• Update the customer’s account balance back to $0.00 via the API, by deleting the pending invoice items, or by modifying the balance directly through the Dashboard

Additional Resources

• Customer Balance: Subscriptions
• Customer Balance: Invoicing
• Upgrading & Downgrading Subscriptions