Selling in Multiple Currencies with Shopify Payments: What this Means for App Developers

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’re announcing the ability to sell in multiple currencies with Shopify Payments. When this feature launches, it will automatically detect a customer’s country, and offer prices in that customer’s local currency, an experience that will carry on through checkout. This pricing will automatically adjust based on foreign-exchange rates and display buyer-friendly prices with simple rounding rules. This update will support 9 key currencies at launch.

"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."

This update is coming to Shopify Plus merchants in early December, but we’re sharing it early with Shopify Partners to ensure you have time to adjust your apps. 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.

The basics: shop currency and presentment currency

The introduction of multi-currency will mean that the currency the merchant sees may not be the currency that is displayed to the buyer. 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.

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 are in either shop currency or presentment currency. It’s therefore very important to make sure that your app is retrieving the correct currency for its use case.

How Shopify’s APIs have evolved to support multi-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.

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.

Migrating to multi-currency

For the technical details of supporting multi-currency in your apps, visit the migration guide in the Shopify Help Center.

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.

"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.

Explore selling in multi-currency on your development stores

It’s important to note that this multi-currency functionality is currently in beta, but 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

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.

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 coming to Shopify Payments, app developers now 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.

Email address

Password

Your store name

Let’s grow your freelance or agency business.

Get design inspiration, practical takeaways and free resources to help you find and delight clients.

Email Address

Thanks for subscribing

You’ll start receiving free tips and resources soon. In the meantime, find out how Shopify’s Partner Program can help you grow your business.

About the Author

David is a Product Manager at Shopify Plus. His team focuses on helping merchants sell to customers around the world. He has a degree in business administration and a degree in computer science, which assists in understanding both the business and technical challenges of international growth.