[New Partner Beta] Selling in Multiple Currencies with Shopify Payments: What this Means for App Developers

[Jordan]

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.

Checkout API

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

Order API

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

Refund API

• [Breaking] POST /calculate and /refunds require currency property on all multi-currency orders.

• Existing properties that return a price defaults to customer currency

Transaction API

• [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.

Customer API

• New currency property returns the currency that the customer used when they paid for their last order.

TenderTransaction API

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

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.

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.

Visit guide

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.

Timeline

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.

[HunkyBill]

Simple Example: Canadian Shop, sells to Canada and USA. 

Prices are shown to Canadians in Canadian dollars. Transacted in Canadian Dollars.

USA customers see prices in USD. That means you are internally subject to the YoYo effect of currency fluctuations for USA customers. They pay in USD though, through your payment gateway, so merchant gets USD cash in their account. What rate do you use to convert for them, and when?

What are your feelings on this YoYo pricing?

[Jordan]

Hey Dave, 

We don’t fluctuate on a minute by minute basis - there's some rate stability that we use throughout the day. The prices are also adjusted to become buyer-friendly, which also insulates from prices going up and down with every rate change. Also: 

so merchant gets USD cash in their account

This isn't is the case. The merchant will get CAD at time of capture since we convert at time of capture. There's some details around staying in sync in your migration guide here. 

[Ryan_Alyea]

PLUS Storeowner here: Can it be disabled?

Many countries require tax-included pricing if you use local currency. For example, while I’m safe if I’m using USD, but if I present in EUR or AUD, I have to have tax-included pricing, which gets to be a major hassle when USD is not tax-included, AUD is 10% tax-included GST, and EUR’s VAT varies by country. 

So unless I’m remitting taxes to that country (or have a waiver that it’s okay for that country to be tax-excluded), and can present tax-included pricing, I’d like to disable it.

(Tax included pricing means that if something is $10 USD, and AUD is 2:1, AU GST is 10%, the customer does not see $20 AUD, the proper price is $22 AUD.)

[HunkyBill]

I have Plus clients that have suffered long and mightily due to the lack of Multi-Currency. So don't get me wrong, the attempts and efforts to make it happen are appreciated. Some things to consider moving forward.

There should be some kind of control other than polling interval on currency exchange rates. For example, to be of use to one of my Plus clients, they want more stability. And how about the old rounding? Showing off prices in a 2-hour period of polling like: 65.23, 65.24, 65.54, 65.33, 65.34, 65.34, 65.77, 65.66)... looks kind of silly. The merchant wants customers to see the same price for a day at least... So if the exchange rate is moving a little every day, the price should remain rock solid in terms of what the customer sees and pays. 

In other words, more options than a 15-minute interval poll to smooth things out for SOME but not all. Obviously there will be penny pinchers in the mix that will be furious at losing a few pennies. 

So ya... way to go... Shopify... but some kind of sliding window/smoother in addition to polling is needed. Hardly seems tough to do at this point... just one more black box to build out.

[David_Cameron]

Ryan, as a merchant you will have control over which currencies you want to enable or disable, and you can change that over time.

[David_Cameron]

In terms of how prices are generated and the 15-minute rate update job, I just want to provide some clarity. We won’t be having a pricing change every 15 minutes, we are just checking if there is a new rate to use in our calculations. The number is provided as guidance to not check every minute when polling. There is rate stability throughout the day with periodic updates that will potentially impact product prices.

On top of the rate stability, we have rounding per currency that allows a merchant to create a buyer-friendly price while also reducing the likelihood customers will see significant fluctuations.

For example, imagine the prices based on FX were at $65.12 with the rounding applied the merchant may want that to go to $65.99 as a way to keep stability. Then the next rate change bumps that to $65.42 again the rounded price would be the same at $65.99

This pricing structure, and how we generate what is displayed is an area that may also evolve as we get feedback and so you’ll notice in the API documentation we highly recommend using the prices retrieved from the Products API.

[Code_Black_Belt]

Hello,

As app developers, we're expected to display prices in the customer currency (i.e., the presentment currency).

I've read the migration guide and I haven't found any information on the required currency formatting.

Will Shopify follow the store currency format for all prices displayed? I mean, regarding currency symbol, currency symbol position, decimal and thousand separators or number of decimals.

For example, Japanese Yen has no decimal digits (see https://en.wikipedia.org/wiki/ISO_4217).

It would be good to know how Shopify will format prices to display them similarly in our apps.

Even better would be to have a version of the Javascript function Shopify.formatMoney() that formats the prices correctly for us.

[HunkyBill]

Are you ever going to fix the bug in pricing that has been part of Shopify since day #1? I mean the one where you type in a price like 1.00 and you get a dollar, but if you type in 1.001 you get 1,001.00. Believe it or not, studies show that people won't pay $1,001 for a $1 item.

I do belive this is related to your under the hood use of a money library that is tuned for currency change, but needs some TLC.

[Ralph-HA]

You mentioned this has no affect on the import part of the Order API.  Does that also mean it has no affect on the other attributes of the Order API.  For example, you can create transactions and refunds using the Order API.

Thanks!

[ClementG]

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?

[Danijel]

100% multi-currency support should be a standard feature. 

Don't give lower end merchants a reason to leave/avoid Shopify's platform. 

[David_Cameron]

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.

[David_Cameron]

HunkyBill, 

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.

[David_Cameron]

Ralph, 

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.

[Zapfor_Apps]

Hi David,

How do I get the refund amount in shop currency, it looks like the refund resoource contains only refund amount in presentmend currency.

[David_Cameron]

Clement, 

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.

[ClementG]

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?!

[David_Cameron]

Danijel, 

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.

[David_Cameron]

Clement, 

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.