Shopify Markets

In Shopify, a market is a group of one or more regions of the world that a merchant is targeting for sales. Merchants have one primary market, and any number of other markets up to a total of 50.

A merchant can configure a different buyer experience for each market depending on their needs. If a store is selling somewhere, then that region is included in one and only one of the store’s active markets — it’s not possible for a visitor in checkout to select a shipping address that’s not included in a market. If your app helps a merchant sell, then you may need to reference their market configuration to know where they sell and what buyer experiences they’ve configured.

When you’re building experiences for customers, don’t expose the merchant’s specific market groupings. Merchants group regions into markets based on their needs, and visitors to a store shouldn’t be asked to guess whether a particular merchant considers Germany to be “Western Europe” or “Central Europe.” Visitors should be told and asked about only the actual geographic regions that a merchant sells.

• Explore an example of how to query for a merchant’s markets configuration with the Admin API.
• Check out an example of how to load a store’s supported countries and languages using the Storefront API.
• Learn about the localization data available in Liquid.

If you have multiple localized versions of a single store, then you should make sure that each visitor interacts with the optimal version of the store. Depending on the merchant’s store configuration, search engines might be able to pre-localize visitors, and Shopify might automatically redirect visitors. However, it’s still possible for a visitor to be browsing in a context for a market that they aren’t actually located in.

Learn how to detect a visitor’s optimal localized experience and help them access it.

For SEO purposes, and to localize marketing efforts, merchants often configure dynamic URLs for their international markets. Shopify Markets makes this automatic for merchants using Liquid storefronts. Developers of custom storefronts are encouraged to follow similar patterns.

Localized web presences for a specific market can take the form of different domains, subdomains, or subfolders. For example, if a store’s primary market is the United States on example.com, then when a Canadian market is created, the merchant can enable a Canadian subfolder at example.com/en-ca. Alternatively, the merchant could choose to configure a Canadian subdomain at ca.example.com or purchase a ccTLD example.ca.

When a merchant translates their storefront, they need a language-specific subfolder for each alternative language. This configuration is automatic for Liquid storefronts. If the same example merchant enables French translations for their United States and Canadian markets, then they’ll get a new URL for each market. The French version of their United States market will be at example.com/fr, and the French version for Canada will be at example.com/fr-ca, ca.example.com/fr, or example.ca/fr depending on the merchant’s configuration for the Canadian market.

• Learn about how to generate dynamic, locale-aware URLs in theme app extensions and script tags.
• Refer to an example of how to use the Admin API to access the root URLs for a shop’s market web presences.

When selling internationally, localized pricing is essential. Automatic conversion with price rounding might be the perfect balance between effort and reward for many merchants, but some merchants need more control. To account for costs or competitive positioning, merchants can adjust product prices in specific international markets up or down by a percentage. Marketing needs or agreements with partners might require merchants to set a fixed, local-currency price for a given product.

• Explore an example of how to query for local prices using the Storefront API.
• Refer to example of how to use the Admin API to preview contextual prices for a product or a specific variant.
• Learn how to use locale-aware URLs and automatically get correct prices in Liquid and the Ajax API.

There are a number of strategies that you can use to configure a market’s international pricing. Automatic conversion can be configured by updating a market’s currency settings. If automatic conversion is insufficient, then you can use price lists to uniformly adjust product prices up or down by a percentage, specify explicit per-variant fixed overrides.

When a merchant’s payment gateway supports selling in local currencies, it is often a merchant’s first step in localizing their shop for international customers. When integrating with a store using Markets, expect to deal with money values in various presentment currencies.

The following concepts in Shopify’s APIs are important to understand when working with multi-currency orders:

Whether for strategic or logistical reasons, sometimes merchants don’t want to sell all of their products in every market. With Shopify Markets, you can restrict specific products from sale in a specific market. Products that are excluded from a market’s catalog are hidden from storefronts, omitted from search results, and blocked from being added to cart when a visitor is browsing in that market’s context. If a customer is browsing in the wrong context, then the restricted product is removed from their cart when they change their shipping address in checkout.

In buyer-facing contexts, a product which is excluded from a market’s catalog will behave just like it was archived or deleted when accessed from that market’s perspective. It will be omitted from lists and not found when queried by handle or ID.

• Refer to an example of how to use the Storefront API to query for products published in a certain context.
• Learn how to restrict products from sale in a market by unpublishing it from that market’s catalog.
• Explore an example of how to use the Admin API to query whether a product is published in a given country.

Translation of store content is a major contributor to successfully selling in an international market, and in some parts of the world it’s essential to reach the domestic market as well. You can assign an alternate language to one or more of a store’s markets, and translations in that language are shared across all those markets. A merchant can also localize their store’s content for a specific combination of market and language. For example, a merchant selling a product titled “Wool sweater” in English might translate it to French as “Pull en laine,” and then localize it for their Canada market as “Chandail en laine.”

When building experiences for a merchant’s customers, you should always query for and display the right content for the customer’s language and country context. Shopify uses a defined fallback order when loading localized content. Consider a United States store with English as its primary language, which also sells in Belgium in French and Dutch. French is the default language for the shop’s Belgian market. When loading content for a customer browsing in a Dutch Belgian context, Shopify follows the following fallback order:

1. Dutch (Belgium)
2. Base Dutch
3. French (Belgium)
4. Base French
5. Base English (shop primary)

Shopify’s buyer-facing APIs, including Liquid and the Storefront API, handle this fallback automatically.

• Learn how to load localized content with the Storefront API.
• Learn how to use locale-aware URLs and automatically get localized content in Liquid and the Ajax API.

To better serve merchants around the world, you should internationalize the user interface of a merchant-oriented app. However, merchant-oriented tools should typically identify a store’s resources by their untranslated base attributes. For example, it might be confusing to a merchant if product titles in an inventory management app were shown in different languages based on their staff member’s language preferences.

If your app helps a merchant build an experience for shoppers, then you should show localized and translated store data in previews, as applicable. If a merchant can use your app to create buyer-facing content, then consider making that content translatable. If you’re storing the content in Shopify as metafields, for example, then your content will be translatable using the GraphQL Admin API. If not, you’ll have to implement your own translation system.

• Refer to an example of how to load translations and localizations with the Admin API to power a merchant-facing preview of a shopper’s experience.
• Learn about how to save translations of merchant-provided content.

Some countries require additional information on international orders which must be collected from customers. If your app creates draft orders or orders with shipping addresses in these countries, then you might need to add the locally required data as “localized extensions” to the order. However, if your app helps merchants fulfill international orders, then you might need to read the locally required data collected in checkout.

Explore the following developer tools and resources to learn more about Shopify Markets.

GraphQL Admin API

Consult the GraphQL Admin API reference to learn more about the Market object.

Building for Markets with the Storefront API

Learn how to build localized customer experiences with the Storefront API and Shopify Markets.

User manual for Shopify Markets

Learn more about how merchants use Shopify Markets to sell internationally.