Support international pricing on storefronts
The prices displayed in a storefront can vary based on a customer's location. This guide shows you how to use the Storefront API to query international prices for products and orders, and explicitly set the context of a cart and checkout.
RequirementsAnchor link to section titled "Requirements"
- You've completed the Getting started with the Storefront API guide.
You're familiar with querying products and collections.
You've set up international pricing in your store.
You're familiar with the concepts introduced in the cart and checkout guides.
Your Headless channel or custom app has the
unauthenticated_write_checkoutsaccess scopes. For more information on requesting access scopes when your custom app is installed, refer to Getting started with OAuth. Learn how to request permissions for Headless channels.
You need to manually enable each country’s currency in a Shopify store's payment settings before you can create a query with different country contexts. Any queries for countries that aren't enabled will default to the store currency.
You're using API version 2022-07 or higher.
Step 1: Make queriesAnchor link to section titled "Step 1: Make queries"
You can use the Storefront API to make the following queries:
- Query available countries and currencies
- Query product prices
- Query price ranges for products
- Query customer orders
Query available countries and currenciesAnchor link to section titled "Query available countries and currencies"
To retrieve a list of available countries and corresponding currencies for a shop, you can query the
localization field on
QueryRoot. Specify a GraphQL directive called
@inContext to get the current country's information.
@inContext directiveAnchor link to section titled "@inContext directive"
A directive provides a way for apps to describe additional options to the GraphQL executor. It lets GraphQL change the result of the query or mutation based on the additional information provided by the directive.
In the Storefront API, the
@inContext directive takes an optional country code argument, and applies this directive to the query or mutation. The following example shows how to retrieve a list of available countries and their corresponding currencies for a shop that's located in France (
Query product pricesAnchor link to section titled "Query product prices"
To retrieve international prices for products, specify the
@inContext(country: countryCode) directive in your query.
This directive also automatically filters out products that aren't published for the country that's specified in the directive. Merchants determine the products that are published for a given market.
If you don't include the
@inContext directive, then the products that are published for the primary market are returned together, with prices in the shop's currency.
The following example shows how to query the price of the first published product in a storefront within the context of Canada (
@inContext(country: CA)). The response returns the price of the product in Canadian dollars.
Query price ranges for productsAnchor link to section titled "Query price ranges for products"
To query the price ranges for products, include the
compareAtPriceRange fields in your request.
priceRange field, you can retrieve the lowest variant's price (
minVariantPrice) and the highest variant's price (
maxVariantPrice). You can also retrieve the compare at price of the product across all variants (
Query customer ordersAnchor link to section titled "Query customer orders"
Order information is returned in the context that it was created. For example, when an app requests the context of France (
@inContext(country: FR)), any previous orders that were created in the United States are returned in USD totals:
Step 2: Create a checkout or cartAnchor link to section titled "Step 2: Create a checkout or cart"
After you've retrieved data about the available countries and currencies, products and their prices, and customer orders on a store, you can create a checkout or a cart.
Create a checkoutAnchor link to section titled "Create a checkout"
While queries use the
@inContext directive to contextualize the response from the server, checkout uses an explicit
buyerIdentity argument as an input to the mutation that will be persisted. Context within the checkout is progressive and can change as customers input their address or additional information.
To create a checkout in the context of a specific country, the checkoutCreate mutation takes an optional
buyerIdentity.countryCode input argument which sets the checkout’s country field. A PRODUCT_UNAVAILABLE error is returned when creating a checkout with a product that is unavailable in the specified country.
When an address is updated on the checkout to include a different country using the checkoutShippingAddressUpdateV2 mutation and the country belongs to a market with customized pricing, the prices that are returned reflect the new country’s prices, or the shop's default prices if the new country isn't enabled. Products are not published for the new country are removed from the checkout.
In the following example, the
@inContext(country: FR) directive is used so that line item variants are returned in EUR prices.
Create a cartAnchor link to section titled "Create a cart"
Similar to a checkout, cart uses an explicit
buyerIdentity argument as an input to the mutation that will be persisted.
buyerIdentity argument contextualizes product variant prices and assures that all products are published for the given country. You can access product variant prices on a cart using the
compareAtAmount fields. The country code that's passed into
buyerIdentity contextualizes the estimated cost of the cart.
When a cart is created in a country context, the resulting response is in the specified country’s currency.
- Learn how to create and update a cart in Shopify with the Storefront API.
- Learn how to manage subscription products by querying selling plans and selling plans groups with the Storefront API.
- Learn how to manage customer accounts with the Storefront API.
- Retrieve metafields with the Storefront API to access additional information from different types of resources.
- Support multiple languages on a storefront with the Storefront API.