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

[Ralph-HA]

Hi David,

   Thanks for the response!  I was actually thinking about how the changes would work when making POST calls for something like transactions through the Order API.  To keep the complexity low in our app, we POST Order data with things like Transactions and Tax Lines through the Order API, not through the individual APIs.  I know these changes will directly affect calls made to the Transaction API, etc but what about using the transactions, etc when making calls via the Order API? 

Let me try and give an example:

Let's say we are POSTing an Order that has a Transaction amount, tax information as well as discounts and shipping.  The API call would look something like this.

{
    "email": "test@example.com",
    "total_tax": "15.00",
    "tax_lines": [{
        "price": "15.00",
        "title": "State Tax"
    }],
    "line_items": [{
        "sku": "1009-1001",
        "price": "50.00",
        "title": "Goblet of Fire",
        "quantity": 2,
        "fulfillment_status": "fulfilled"
    }],
    "discount_codes": [{
        "code": "",
        "amount": "5.00"
    }],
    "shipping_lines": [{
        "price": "7.0",
        "title": "USPS (Priority Mail)"
    }],
    "transactions": [{
        "amount": "145.00"
    }]
}

Area all of these attributes (transactions, tax_lines, shipping_lines, discount_codes) unaffected with the Order API as mentioned in the original post?

Thanks again for your help David and let me know if you need me to explain anything else.

[Ralph-HA]

Hi David,

   Thanks for the response!  I was actually thinking about how the changes would work when making POST calls for something like transactions through the Order API.  To keep the complexity low in our app, we POST Order data with things like Transactions and Tax Lines through the Order API, not through the individual APIs.  I know these changes will directly affect calls made to the Transaction API, etc but what about using the transactions, etc when making calls via the Order API? 

Let me try and give an example:

Let's say we are POSTing an Order that has a Transaction amount, tax information as well as discounts and shipping.  The API call would look something like this.

{
    "email": "test@example.com",
    "total_tax": "15.00",
    "tax_lines": [{
        "price": "15.00",
        "title": "State Tax"
    }],
    "line_items": [{
        "sku": "1009-1001",
        "price": "50.00",
        "title": "Goblet of Fire",
        "quantity": 2,
        "fulfillment_status": "fulfilled"
    }],
    "discount_codes": [{
        "code": "",
        "amount": "5.00"
    }],
    "shipping_lines": [{
        "price": "7.0",
        "title": "USPS (Priority Mail)"
    }],
    "transactions": [{
        "amount": "145.00"
    }]
}

Area all of these attributes (transactions, tax_lines, shipping_lines, discount_codes) unaffected with the Order API as mentioned in the original post?

Thanks again for your help David and let me know if you need me to explain anything else.

[David_Cameron]

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.

[Ralph-HA]

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

[David_Cameron]

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.

[Zapfor_Apps]

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?

[Ralph-HA]

Thanks for the clarification, David.  I appreciate it. 

[David_Cameron]

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.

[Zapfor_Apps]

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?

[David_Cameron]

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.

[Zapfor_Apps]

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? 

[Kenny_Johnson]

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?

[Kenny_Johnson]

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?

[Code_Black_Belt]

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]

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]

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]

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

thanks

[Bharath]

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]

Hello Shopify Team, 

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

[Zameer]

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.