Multi-currency customers
Change the billable currency for any customer to accept multiple currencies.
Use the Invoicing API to issue an invoice to a customer in a different currency. With the multi-currency customers feature, you can bill the same Customer using a different currency than what’s set as their default currency, and change the currency for a customer’s subscriptions. You can’t have two active subscriptions with different currencies.
This guide also explains how to create a credit note and inspect a customer’s credit balance in all assigned currencies. For illustrative purposes, we use the Canadian Dollar (CAD).
Create an invoice
Before you invoice a customer, create an invoice item by passing in the customer id, amount, and currency. Only add invoice items to a single customer at a time to avoid adding them to the wrong one.
The maximum number of invoice items is 250. Creating an invoice adds up to 250 pending invoice items with the remainder to be added on the next invoice. To see your customer’s pending invoice items, see the Customer details page or set the pending attribute to true when you use the API to list all of the invoice items.
Note
A CAD invoice doesn’t apply any customer credit balance denominated in any currency other than CAD. Additionally, it ignores any amount-off coupons you applied to the customer that are denominated in non-CAD currency.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
You must pass in the currency parameter when you issue a multi-currency invoice. The currency parameter dictates which invoice items get pulled into the invoice. For example, if you were to create two invoice items—one in USD and the other in CAD—for the same customer, setting the currency to CAD would only pull in the CAD invoice item (ignoring the USD invoice item).
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Create a credit note
If there’s an issue with the invoice, you can create a credit note. If you need to apply the credit to the customer’s credit balance (as opposed to back to the original payment method), Stripe allocates the credit amount to the CAD-specific credit balance.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Inspect the credit balance
To see how much credit a customer has in each currency, use the invoice_credit_balance parameter:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
The customer’s credit balance is drawn down from the next CAD invoice created for this customer. It won’t, however, be drawn down for invoices created in different currencies.