Global expansion is booming, and today’s buyers are expecting a personalized purchasing experience, with prices displayed in their own local currencies. As Shopify merchants expand their reach to attract international customers, they are quickly noticing that offering this personalized touch raises a host of operational and technological challenges.

To address these challenges, we launched the ability to sell in multiple currencies with Shopify Payments to Plus merchants in February 2019. Today, we’re happy to announce that this ability is rolling out to all merchants over the next couple of months.

Our selling in multiple currencies feature offers prices in that customer’s local currency, an experience that carries through to the checkout. This pricing automatically adjusts based on foreign-exchange rates and displays buyer-friendly prices with simple rounding rules. This feature currently supports 9 key currencies: GBP, AUD, CAD, EUR, HKD, JPY, NZD, SGD, and USD.

As a Shopify Developer, we want to ensure you have the information you need to adjust your apps to account for this feature. Adjusting your apps will allow you to fully take advantage of this new opportunity by reaching new, wider groups of merchants and enhancing the functionality you offer.

"Adjusting your apps will allow you to fully take advantage of this new opportunity by reaching new, wider groups of merchants and enhancing the functionality you offer."

In this blog post, we’ll walk you through what selling in multiple currencies with Shopify Payments means for your apps, and the changes you need to make to your apps to better support your merchants with multiple currencies.

Build apps for Shopify merchants

Whether you want to build apps for the Shopify App Store, offer private app development services, or are looking for ways to grow your user base, the Shopify Partner Program will set you up for success. Join for free and access educational resources, developer preview environments, and recurring revenue share opportunities.

Sign up

The basics: shop currency and presentment currency

To support this change, we are introducing two concepts that lie at the foundation of multiple currency. They are:

Shop currency: this is the currency that product prices are originally set in by the merchant, and is the currency used for reporting and analytics
Presentment currency: this is the currency the specific customer sees on the storefront, cart, and checkout

The distinction between these two concepts is extremely important for app developers, since you can no longer assume that the currency you currently retrieve from the Shopify API is in either shop currency or presentment currency. It is therefore very important to make sure that your app is retrieving the correct currency for its use case.

Rounding rules

Selling in multiple currencies for Shopify Payments automatically sets product prices based on the current foreign exchange rate, adds a foreign exchange conversion fee, and then rounds up the prices. This rounded price is then displayed on the merchant’s storefront when a customer selects a given currency.

How Shopify’s APIs have evolved to support multi-currency

selling in multiple currencies: currency

To evolve with the internationalization needs of merchants, Shopify has put a lot of effort into adding multi-currency support to many core areas, including products, orders, checkouts, transactions, refunds, and more. And while these changes aren’t ‘breaking’ in the conventional sense, they present an opportunity for you to update your app to operate in a new multi-currency world. Doing so opens the door to work with merchants who sell around the globe, and makes your app relevant in markets beyond your own.

There’s also a risk in not updating your app—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 use case.

To take advantage of this opportunity—and to keep merchants and buyers happy—you must update your apps to ensure they get the relevant shop currency or presentment currency for their particular use case. The following 6 API changes can all impact the merchant and customer experience your app offers. Read on to learn what’s changing, and how your app can adapt.

1. Product and product variant APIs

Product and product variant APIs help with storefront search, sending email notifications with product pricing, and providing product price feeds. With the multi-currency updates, users of these APIs can no longer expect that the product’s price is the same price that will be presented to the customer.

Under the new conditions, the product price as it is used today will always be that of the shop currency. In order to retrieve the product price in the various supported currencies, we are introducing new attributes to the product variant model. If your app presents the product price to the customer in some way, we highly recommend you use these new attributes. Otherwise, you may be displaying inaccurate information to merchants and shoppers.

2. Checkout API

Once a shop enables multiple currencies, the checkout’s default currency will always be in the presentment currency, the currency that is presented to the customer. So, for example, if a customer is checking out in Japanese yen, the currency and all values with be in Japanese yen.

When creating new checkouts, you can specify any supported presentment currency. If no currency is specified in the request, the checkout will default to shop currency.

3. Order API

The Order API serves many different use cases, from reporting, upsell marketing, accounting, shipping and fulfillment, and more. It’s important to note that the current Order API will default to expose all shop currency values.

Because of this, we are introducing new fields to act as the source of truth for both presentment currency and shop currency. We recommend using these new fields to ensure your app is reading the values in the most relevant currency for your app’s use case.

4. Refund API

All read requests in the Refund API will default to presentment currency. When creating new refund transactions, apps must now always pass the currency field. Failing to pass currency on when creating refund transactions on multi-currency orders will return an error.

5. Transaction API

New transactions, specifically capture and refund transactions, are required to include the currency field on all multi-currency orders, with the eventual requirement for all orders if an amount value is passed in the API request. This requirement will ensure that transactions aren’t captured in less than the original authorized value.

By default, all transactions will return values in presentment currency. If you want to read transactions in the shop currency, you can do so by passing the param ?in_shop_currency=true.

However, we highly recommend using TenderTransaction API (see below) as an alternative.

6. TenderTransaction API

We’re excited to introduce a new API that allows developers 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.

Tender transactions represent transactions that modify the shop's balance. If your app currently uses the Transactions API for reporting, accounting, or dealing with transactions in shop currency, we recommend using the new TenderTransaction API.

6. Liquid API

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. If you’re showing a currency or a price to a customer on the storefront, you’ll want to update your app to use the new Liquid API additions.

7. AJAX API

All monetary values returned by the following endpoints now reflect the customer’s presentment currency::

/cart.js
/products/{product-handle}.js
/recommendations/products.json
/cart/shipping_rates.json

Shopify Plus differences

There are some key differences in multi-currency functionality for Shopify Plus merchants. These are:

Shopify Plus merchants will have the right currency automatically selected for buyers based on the buyer’s IP address. For example, a merchant in the US will have their shop prices displayed in USD, but a shopper in Japan will see those prices displayed in the Japanese yen.
Shopify Plus merchants can customize the rounding rules used on their store based on their preference.

Explore selling in multi-currency on your development stores

The core features of multi-currency can be accessed through development stores. All you need to access it is to be a Shopify Partner and to have a Shopify Payments account. Not yet a Shopify Partner? Sign up today.

How to enable selling in multiple currencies on your 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.

Multi-currency features available to Plus merchants can be found in the Shopify Plus Partner sandbox stores.

Build apps for Shopify merchants

Whether you want to build apps for the Shopify App Store, offer private app development services, or are looking for ways to grow your user base, the Shopify Partner Program will set you up for success. Join for free and access educational resources, developer preview environments, and recurring revenue share opportunities.

Sign up

Going international with multi-currency selling

Selling in multiple currencies is important for merchants, so it’s equally important that Shopify Partners have the tools they need to meet that demand. With multi-currency capabilities now available with Shopify Payments, app developers have the opportunity to build solutions for merchants who work globally. Making the necessary changes to your apps will not only help you rise to the challenge—you’ll also help make the commerce experience better for shoppers around the world.

If you have any questions about getting your app ready for this update, don’t hesitate to reach out in the API forums.

David Cameron