Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
Invoicing
    Overview
    How Invoicing works
    API quickstart
    Integrate with the API
    Invoicing without code
    Invoice lifecycle
    Preview invoices
    Edit invoices
    Schedule invoice finalisation
    Status transitions and finalisation
    Send customer emails
    Generate credit notes
    Invoice customers
    Customers
    Customer credit balance
    Customer tax IDs
    Invoice payments
    Hosted Invoice Page
    Create invoice payment plans
    Accept partial payments
    Payment methods for invoices
    Automated collections
    Invoice customisation
    Customise invoices
    Invoice rendering templates
    Group invoice line items
    Summarise line items
    Global invoicing
    Best practices
    Multi-currency customers
    Other invoicing features
    Products and prices
    Manage bulk invoice line items
    Taxes
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueInvoicing

Multi-currency customers

Change the billable currency for any customer to accept multiple currencies.

If you need to sell in multiple currencies but have each individual customer use a single currency, see multi-currency Prices.

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 a customer credit balance denominated in USD or any other currency other than CAD. Additionally, any amount-off coupons you applied to the customer that are denominated in non-CAD currency are ignored.

Command Line
cURL
curl https://api.stripe.com/v1/invoiceitems \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}
\ -d amount=1000 \ -d currency=cad

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
cURL
curl https://api.stripe.com/v1/invoices \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}
\ -d collection_method=send_invoice \ -d days_until_due=30 \ -d pending_invoice_items_behavior=include \ -d currency=cad

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
cURL
curl https://api.stripe.com/v1/credit_notes \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d invoice={{INVOICE_ID}} \ -d reason=duplicate \ -d amount=1000 \ -d credit_amount=1000

Inspect the credit balance

To see how much credit a customer has in each currency, use the invoice_credit_balance parameter:

Command Line
cURL
curl -G https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "expand[]"=invoice_credit_balance

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.

See also

  • Integrate with the Invoicing API
  • Manage customers
  • Products and prices
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access programme.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc