Back to Developer changelog

We're launching multi-currency with Shopify Payments, which lets merchants offer prices in their customers' local currencies

API

Effective October 24, 2018

Action required

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 a 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 the 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.

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.

Note: 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

  1. 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”.
  2. 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.