d
Topic
Jordan API Product / Developer Experience
Posts:
272
Last edited about 2 months ago
g
1
upvotes

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

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.

i
Replies
Posts:
3851
about 2 months ago

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?

 

Custom Shopify Apps built just for you! hunkybill@gmail.com http://www.resistorsoftware.com
Jordan API Product / Developer Experience
Posts:
272
about 2 months ago

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 Shopify Partner rofish.net
Posts:
26
about 2 months ago

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

Posts:
3851
about 2 months ago

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.

Custom Shopify Apps built just for you! hunkybill@gmail.com http://www.resistorsoftware.com
David Cameron Shopify Employee
Posts:
12
about 2 months ago

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 Shopify Employee
Posts:
12
about 2 months ago

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.

Posts:
122
Last edited about 2 months ago

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.

Posts:
3851
Last edited about 2 months ago

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.

Custom Shopify Apps built just for you! hunkybill@gmail.com http://www.resistorsoftware.com
Posts:
620
about 2 months ago

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 Member
Posts:
20
about 2 months ago

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 Shopify Employee
Posts:
12
about 2 months ago

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 Shopify Employee
Posts:
12
about 2 months ago

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 Shopify Employee
Posts:
12
about 2 months ago

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.

Posts:
71
about 2 months ago

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.

SimplyCost - Add costs and track profit (https://apps.shopify.com/simplycost)
David Cameron Shopify Employee
Posts:
12
about 2 months ago

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.

Posts:
620
about 2 months ago

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 Shopify Employee
Posts:
12
about 2 months ago

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 Shopify Employee
Posts:
12
about 2 months ago

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.

David Cameron Shopify Employee
Posts:
12
about 2 months ago

Clement and Zapfor Solutions,

The refund resource will now provide you with a price_set for every line_item so you'll be able to choose which value you are most interested in. We're going to get the migration guide updated as well.

Posts:
14
about 2 months ago

Hi David,

   Thanks for getting back so quickly.  

   I think what I'm looking for is a little different.  I realize the API is changing for the refunds and transactions but I was wondering if this is true also when POSTing these attributes with Orders API.  For on of our apps, we post transactions, taxe_lines, discounts and shipping_lines with the Order API to ensure we don't run into N+1 problems.  I was wondering if the API changes will have an affect on the Order API in this way.  

Below is an example API call we would make with the above attributes.  Can you verify that making this call will still work without the new pricing changes.

{
	"name": "9000201",
	"tax_lines": [{
		"price": "$10.00",
		"title": "State Tax"
	}],
	"total_tax": "15.00",
	"line_items": [{
		"sku": "1009-1001",
		"price": "50.00",
		"title": "Goblet of Fire",
		"quantity": 2,
		"fulfillment_status": "fulfilled"
	}, {
		"sku": "1009-3001",
		"price": "25.00",
		"title": "Golden Snitch",
		"quantity": 1,
		"fulfillment_status": "fulfilled"
	}],
	"send_receipt": false,
	"transactions": [{
		"amount": "145.00"
	}],
	"shipping_lines": [{
		"price": "5",
		"title": "Fedex Ground"
	}],
	"billing_address": {
		"zip": "2215",
		"city": "Boston",
		"country": "US",
		"address1": "4 Yawkey Way",
		"province": "MA",
		"last_name": "Dent"
	},
	"shipping_address": {
		"zip": "2215",
		"city": "Boston",
		"name": "Led Dent",
		"country": "US",
		"address1": "4 Yawkey Way",
		"province": "MA"
	}
}

As you can see we are not providing the new currency fields with the other Order attributes.  Let me know if you need any more clarification.

Thanks for all your help!

Ralph

EZ Inventory | EZ Exporter | Slacky | EZ Importer | https://apps.shopify.com/partners/highview-apps
David Cameron Shopify Employee
Posts:
12
about 1 month ago

Ralph,

Considering it looks like you're importing an entire order (including its transactions) you should be fine. The updates to transactions really just impact multi-currency orders that were created through the online store that have applications that want to interact with those transactions.

Posts:
71
about 1 month ago

Hi David,

The refund resource will now provide you with a price_set for every line_item so you'll be able to choose which value you are most interested in. We're going to get the migration guide updated as well.

Thanks, that's great!

What about the order_adjustments node (under refunds), will it have a price_set for every order_adjustment?

 

 

SimplyCost - Add costs and track profit (https://apps.shopify.com/simplycost)
Posts:
14
about 1 month ago

Thanks for the clarification, David.  I appreciate it. 

EZ Inventory | EZ Exporter | Slacky | EZ Importer | https://apps.shopify.com/partners/highview-apps
David Cameron Shopify Employee
Posts:
12
about 1 month ago

Zapfor, 

The refund portion of the migration guide has just been updated to hopefully answer your question  https://help.shopify.com/en/api/guides/multi-currency-migration-guide#refund-resource 

Let me know if we've missed something.

Posts:
71
about 1 month ago

Hi David,

Yes it does answer my question.

One more question :) I am in a country where Shopify Payments is not supported. How do I test in this case?

SimplyCost - Add costs and track profit (https://apps.shopify.com/simplycost)
David Cameron Shopify Employee
Posts:
12
about 1 month ago

Zapfor,

Great question. I'm going to see if there are any alternatives, unfortunately as of right now you'll need to enable Shopify Payments and connect a bank account to get the Accepted currencies option to display.

You should be able to play around with the actual APIs you just won't get as much interesting data without the ability to enable additional currencies.

Posts:
71
24 days ago

Hi David,

Thanks. For Refunds, there seems to be discrepency between the migration guide and the first post of this thread.

In the first post of this thread (under Refund API) it says:

Existing properties that return a price defaults to customer currency

However, in the migration guide  :

refund_line_items and order_adjustments, are in the shop currency.

Can I assume the migration guide is the latest version? 

 

SimplyCost - Add costs and track profit (https://apps.shopify.com/simplycost)
Posts:
3
22 days ago

Hey Jordan,

If the merchant always receives funds in their shop currency. Does this mean that the amount received at capture could differ from what was authorized due to exchange rate fluctuation between capture and authorization?

Posts:
3
21 days ago

One more question, when will the API changes take effect, will all customers be pushed to multi-currency automatically on the 17th, will it just be Plus customers or just when Plus customers enable another currency?

Posts:
122
21 days ago
g
1
upvotes

Hello David,

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.

We've finished our exploratory testing of the new feature and we would like to provide some feedback.

First, as you pointed out, the currency formatting defined in the store is only respected when the main currency is displayed. If any other of the presentment currencies is selected, the currency formatting is not respected any more. For example, decimals are always displayed (even if the configuration uses {{amount_no_decimals}}) and the currency code (USD, CAD, GBP...) is never displayed (even if it is part of the currency configuration). This may confuse merchants and break compatibility with apps and themes that rely on correct currency formatting.

On the other hand, the hard-coded currency formatting for EUR uses comma (,) as a decimal separator. Please note that the decimal separator is not related to the currency but to the language. English-speaking countries, like Ireland, use dot (.) as decimal separator whereas French-speaking countries, for example, use comma. Ireland currency is EUR and prices look like €7.50

Indeed, the position of the currency symbol is also relative to language. English language displays the currency symbol on the left side while French language shows it on the right. So it would be €7.50 in Ireland and 7,50€ in France (both countries currency is EUR).

Things are a bit more complicated with language variantes. In Spanish, for example, the symbol position and decimal separator depend on the variant (for example, $7.50 is Spanish (Mexico) and 7,50$ is Spanish (Spain)).

On the other hand, we noticed a corner case with the rounding up: $0.01 prices are rounded up to $1. This may make some sense when rounding $79.01 to $80 but for prices lower than $1 maybe it's not the best idea (thing on stores selling tons of very cheap parts, as, for example, screws and bolts.

Please shed some light on whether these things will be considered issues (and, consequently, fixed at some point) or ignored (and we have to follow these rules for our implementations).

Thanks in advance.

Aun Wasti Member
Posts:
1
18 days ago

Hi, I am not a shopify geek I've worked with some clients retrieving orders and products and some times with transaction of their shopify APIs. With the above mention changes of multi currency in APIs, do I still have to wonder for changes in my implementations as my clients doesnot use multi currencies i.e. they have same shop and presement currency?

sebryu Member
Posts:
2
Last edited 10 days ago

Hello everyone. I'm developer from Klarna Payments app and I would like to ask two questions.
1. Do you have exact date when multiple currencies would go live for all shopify plus merchants?
2. Will Checkout API changes also work with Checkout Anywhere API? I'm testing it for development store and I get some values in presentment currency and other values in merchant currency. E.g:


Shopify admin/checkout

"payment_due": "364.10",
"subtotal_price": "356.95",
"total_price": "364.10",


Shopify anywhere/checkout

"payment_due": "364.10",
"subtotal_price": "405.62",
"total_price": "413.62",


Additionally - anywhere/checkout doesn't have presentment_currency field, and has "available_shipping_rates" array with merchant currency prieces.
We would really like to stick with anywhere/checkout because currently we don't have read_checkouts permissions on our merchants.

Kevster Member
Posts:
1
8 days ago

Hi, can I settle in different currencies? USD to USD, euro to Euro etc etc

 

thanks

Bharath Member
Posts:
17
8 days ago

Hi Jordan/David, 

I'm testing refund, transaction changes on a multi-currency enabled store. As per documentation, currency is a mandatory field while calculating the refunds or while creating the refunds. But we're not getting any error when there is no currency in the request. So this change is not live for multi-currency beta stores? it's automatically reflecting the order's currency in the result. If we're giving wrong currency in the request then it's erroring out properly.

Also, currency is required only for multi-currency stores or is it for all? i.e if a store didn't enable multi-currency, do we really need to send currency field?

In the case of multi-currency enabled stores, currency field is mandatory for other currency orders or is it mandatory only for all orders?

Bharath Member
Posts:
17
1 day ago

Hello Shopify Team, 

Any update on the above query? we're not able to proceed further because of above queries.

Zameer Masjedee Shopify Employee
Posts:
89
about 9 hours ago

Hey Zapfor,

There seems to be discrepency between the migration guide and the first post of this thread [...] can I assume the migration guide is the latest version?

Refunds will actually be in presentment (customer) currency. The migration guide will be corrected to reflect this.

Kenny,

Does this mean that the amount received at capture could differ from what was authorized due to exchange rate fluctuation between capture and authorization?

No, these prices will never differ because we store the rate used to determine the prices on the order. However, for future transactions, such as refunds, a new live rate is used.

When will the API changes take effect, will all customers be pushed to multi-currency automatically on the 17th

A small subset of Plus customers will have the multi-currency beta enabled on December 17th, with the remaining Plus merchants having it rolled out in January 2019 as part of the general release.

Code Black Belt,

The currency formatting defined in the store is only respected when the main currency is displayed

It seems as though this is by design. We recognize this poses some challenges but a more satisfactory solution is being explored.

Please note that the decimal separator is not related to the currency, but to the language [...] the position of the currency symbol is also relative to language.

In regards to local specific formatting, these are both topics in discussion with our teams. There are no timelines on when it will potentially be resolved, but we're aware they're both things that need to get addressed.

Aun,

Do I still have to wonder for changes in my implementations as my clients does not use multi currencies

You should have also received an email on November 20th if your app has been sending deprecated requests during November. The changes only impact multi-currency orders with shops that choose to enable it.

Sebryu,

Will Checkout API changes also work with Checkout Anywhere API?

No, the 'anywhere/checkout' endpoint will not be supporting multi-currency as it uses a legacy checkout controller. You would need to migrate to the 'admin/checkout' endpoint to take advantage of the new functionality, which would require you to add read_checkouts to your requested scopes.

Kevster,

Can I settle in different currencies?

If by ‘settle’ you are referring to payouts, this guide explains what currencies you can get paid out in with Shopify Payments. Otherwise all payments gets converted to your store currency.

Bharath,

So this change is not live for multi-currency beta stores?

The change is definitely live for development stores. Can you please share exactly what request you were making so I can take a deeper look? The `currency` field is required for all requests on multi-currency orders where `amount` is also passed. This goes for creating refunds/transactions and refund calculations. If amount is not specified `currency` is not required.
 

If a store didn't enable multi-currency, do we really need to send currency field?

No, it is only required for multi-currency orders. You can check to see if a shop has multi-currency enabled by checking how many currencies are returned by the `/admin/shop.json` endpoint in the `enabled_presentment_currencies` array.

In the case of multi-currency enabled stores, currency field is mandatory for other currency orders or is it mandatory only for all orders?

It is only mandatory for multi-currency orders.

 

For any further multi-currency related questions, we would recommend creating a separate thread in the API forums.