Today, we’re excited to announce a new partner beta: Selling in multiple currencies with Shopify Payments. This update will enable merchants to offer product prices in their customer’s local currency, an experience that will carry on through checkout.
This update is expected to launch to all Shopify Plus stores in early December, but we’re sharing it early with you now to ensure you have time to update your apps to support the multi-currency needs of your users and their customers.
Why should I update my app?
By adding support for multiple currencies, Shopify has made changes to several core areas, including products, checkouts, transactions, orders, liquid, and more. These changes are not breaking in the conventional sense, but they do mean that existing property values that return a price might not represent what they have in the past. You can no longer assume that the price you currently retrieve from the Shopify API is in either the shops primary currency or the currency presented to the customer. Since the shop currency and customer currency can be different, you’re running the risk of confusing customers or merchants if you’re using the wrong currency for your app’s use case.
Key API deprecations, additions, and breaking changes
For a comprehensive list of all multi-currency related API changes, see our migration guide.
Product and product variant APIs
Existing properties that return a price (i.e variant.price) default to shop’s primary currency
New presentment_prices property returns a product variant’s prices and compare-at prices in all supported currencies.
Existing properties that return a price defaults to customer currency
Existing checkout.currency property returns the shop’s currency
New checkout.presentment_currency property returns the currency that the customer selected at checkout
POST /checkouts - you can include the new presentment_currency property to set a customer currency for the checkout. If you don’t include the property, then the presentment currency and all existing properties that return a price default to the shop’s primary currency.
Existing properties that return a price defaults to shop’s primary currency
Various new properties are now available throughout the Order API to retrieve amounts in the customer’s currency.
Order import does not currently support multi-currency.
[Breaking] POST /calculate and /refunds require currency property on all multi-currency orders.
Existing properties that return a price defaults to customer currency
[Breaking] POST /transactions, specifically capture and refund transactions, require currency field on all multi-currency orders. This requirement will ensure that transactions aren’t captured in less than the original authorized value.
Existing properties that return a price defaults to customer currency. If you want to read transactions in the shops primary currency, pass the param ?in_shop_currency=true in all GET requests. However, we highly recommend using TenderTransaction API (see below) as an alternative.
New currency property returns the currency that the customer used when they paid for their last order.
New API to retrieve only the transactions that represent money passing between the merchant and a customer. A tender transaction with a positive amount represents a transaction where the customer paid money to the merchant. A negative amount represents a transaction where the merchant refunded money back to the customer.
We’ve added a number of important changes to our Liquid API from currency selectors, new form filters, and various new liquid objects to better support customers shopping in their local currencies.
How do I update my apps to support multi-currency users?
To learn how to migrate your app to support multi-currency workflows, visit the migration guide in the Shopify Help Center.
Explore selling in multi-currency on your development stores
It’s important to note that this multi-currency functionality is currently in beta and can only be accessed through development stores.
To get started exploring the functionalities of multi-currency, follow the setup instructions outlined in the Help Center to enable multi-currency on your development store. This will allow you to beta test selling in multiple currencies.
Please note that this feature is currently in beta and still a work in progress. Expect there to be changes to functionality and documentation as new features are introduced and bugs are addressed.
October 24, 2018: Partners can begin testing Selling in Multiple Currencies with Shopify Payments on their development stores. Multi-currency API changes are live across all shops with use of the request header “X-Shopify-Api-Features: multi-currency”.
Early December, 2018: The multi-currency feature is expected to release to all Shopify Plus merchants. Please ensure that your apps are updated by this date.
If you have any questions about getting your app ready for this update, don’t hesitate to reach out in the thread below.
Well done Shopify, this is a very welcome addition!
I have a few questions after reading the docs / guides.
1) Beside the facts that they don't exactly have the same properties, is there a difference between using the existing Transaction endpoint with in_shop_currency=1 and using the new TenderTransaction endpoint?
I guess I don't quite see the point of the new endpoint if we can get the same thing with the existing endpoint.
2) Currencies.json: I don't see a rate property. Is this by design?
3) Refunds. This one confused me the most.
When fetching a refund, are the amounts in the presentment or shop currency?
Does it depend on which property we are looking at? (orded_adjustments vs refund_line_items vs transactions)
In the example in the guide, it seems that the amount are in the presentment currency, but that seems inconsistent since the order's line items are in the shop's currency. Unless a refund's refund_line_items and order's line_items are not treated the same?
100% multi-currency support should be a standard feature.
Don't give lower end merchants a reason to leave/avoid Shopify's platform.
Code Black Belt,
For the shop currency we use the currency formatting setting, when other currencies are selected we use our formatting for those currencies as part of the liquid drops. Let us know once you've had a chance to play around if we're missing something that impacts your ability to provide the experiences you're looking for.
I see what you mean in terms of the price input experience, I personally don't have a lot of context on the history there. I suspect it's something related to how different currencies use periods and commas to indicate different things.
If you're referring to Refunds and Transactions, we have made changes there and are asking api users to be explicit about the currency used in those POST requests.
Refunds Transactions are links to the Migration guide with some examples in REST and GraphQL
Let me know if you meant something different.
How do I get the refund amount in shop currency, it looks like the refund resoource contains only refund amount in presentmend currency.
I'll answer a couple of your questions now.
2) For currencies, we don't include the rates, because we want partners to leverage the Product and Product Variant APIs to grab the prices for products rather than trying to reverse engineer them. This will allow us to iterate on the pricing formula without breaking the ecosystem.
3) For Orders, you'll notice that there is a price_set included for all the various types of line items. You can choose from that set which you'd prefer for your particular integration, either presentment or shop.
For GET requests on Refunds those will be in presentment_currency.
Thanks David but if I do a GET on a order and I inspect the order.refunds.refund_line_items, those will be in presentment_currency too?
That would mean that order.line_items and order.refunds.refund_line_items are expressed in differency currencies?!
We're starting with Shopify Plus merchants and eventually rolling out to all merchant plans. Appreciate the excitement as we work on getting it there.
I'm going to check back with the team on the refunds GET request and get back to you tomorrow. I know the orders.line_items have a price_set so you'll have both shop values and presentment values. orders.line_items.price_set.shop_money or orders.line_items.price_set.presentment_money.