The prices displayed in a storefront can vary based on a customer's location. This guide shows you how to use the [Storefront API](/docs/api/storefront) to query international prices for products and orders, and explicitly set the context of a cart. ## Requirements - You've completed the [Getting started with the Storefront API](/docs/storefronts/headless/building-with-the-storefront-api/getting-started) guide. - You're familiar with [querying products and collections](/docs/storefronts/headless/building-with-the-storefront-api/products-collections/getting-started). - You've set up [international pricing](/docs/apps/build/markets/build-catalog) in your store. - You're familiar with the concepts introduced in the [cart](/docs/storefronts/headless/building-with-the-storefront-api/cart/manage) guide. - Your Headless channel or custom app has the `unauthenticated_read_product_listings`, `unauthenticated_read_customers` and `unauthenticated_write_checkouts` [access scopes](/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](/docs/apps/build/cli-for-apps/app-configuration). Learn how to [request permissions for Headless channels](/docs/storefronts/headless/building-with-the-storefront-api/manage-headless-channels#request-storefront-permissions). - You need to [manually enable each country’s currency](https://help.shopify.com/en/manual/payments/shopify-payments/multi-currency/setup) in a Shopify store's payment settings before you can [create a query with different country contexts](#query-available-countries-and-currencies). 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 queries You can use the Storefront API to make the following queries: - [Query available countries and currencies](#query-available-countries-and-currencies) - [Query product prices](#query-product-prices) - [Query price ranges for products](#query-price-ranges-for-products) - [Query customer orders](#query-customer-orders) ### 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 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 (`@inContext(country: FR)`). ```graphql query @inContext(country: FR) { localization { availableCountries { currency { isoCode name symbol } isoCode name unitSystem } country { currency { isoCode name symbol } isoCode name unitSystem } } } ``` ```json { "data": { "localization": { "availableCountries": [ { "currency": { "isoCode": "CAD", "name": "Canadian Dollar", "symbol": "$" }, "isoCode": "CA", "name": "Canada", "unitSystem": "metric" }, { "currency": { "isoCode": "EUR", "name": "Euro", "symbol": "€" }, "isoCode": "FR", "name": "France", "unitSystem": "metric" } ], "country": { "currency": { "isoCode": "EUR", "name": "Euro", "symbol": "€" }, "isoCode": "FR", "name": "France", "unitSystem": "metric" } } } } ``` ### 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](https://help.shopify.com/en/manual/markets/publishing-products-with-markets). 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. ```graphql query allProducts @inContext(country: CA) { products(first: 1) { edges { node { variants(first: 1) { edges { node { price { amount currencyCode } } } } } } } } ``` ```json { "data": { "products": { "edges": [ { "node": { "variants": { "edges": [ { "node": { "price": { "amount": "30.0", "currencyCode": "CAD" } } } ] } } } ] } } } ``` ### Query price ranges for products To query the [price ranges](/docs/api/storefront/reference/products/productpricerange) for products, include the `priceRange` and `compareAtPriceRange` fields in your request. Within the `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 (`compareAtPriceRange`). ```graphql query productPriceRanges @inContext(country: CA) { products(first: 1) { edges { node { title priceRange { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } compareAtPriceRange { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } } } } } ``` ```json { "data": { "products": { "edges": [ { "node": { "title": "French Bulldog with headphones sketch", "priceRange": { "minVariantPrice": { "amount": "30.00", "currencyCode": "CAD" }, "maxVariantPrice": { "amount": "40.00", "currencyCode": "CAD" } }, "compareAtPriceRange": { "minVariantPrice": { "amount": "28.00", "currencyCode": "CAD" }, "maxVariantPrice": { "amount": "40.00", "currencyCode": "CAD" } } } } ] } } } ``` ### 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: ```graphql query customerOrders @inContext(country: FR) { customer(customerAccessToken: "token") { orders(first: 10) { edges { node { totalPrice { amount currencyCode # order's currency - USD (point in time) } lineItems(first: 10) { edges { node { originalTotalPrice { amount currencyCode # order's currency - USD (point in time) } variant { price { amount currencyCode # EUR variant’s currency (passed context) } } } } } } } } } } ``` ```json { "data": { "customer": { "orders": { "edges": [ { "node": { "totalPrice": { "amount": "90.00", "currencyCode": "USD" }, "lineItems": { "edges": [ { "node": { "originalTotalPrice": { "amount": "90.00", "currencyCode": "USD" }, "variant": { "price": { "amount": "70.0", "currencyCode": "EUR" } } } } ] } } } ] } } } } ``` ## Step 2: Create a 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 cart. While queries use the `@inContext` directive to contextualize the response from the server, cart uses an explicit `buyerIdentity` argument as an input to the mutation that will be persisted. Context within the cart is progressive and can change as customers input their address or additional information. The `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 `amount` and `compareAtAmount` fields. The country code that's passed into `buyerIdentity` contextualizes the estimated cost of the cart. ```graphql mutation { cartCreate(input: { buyerIdentity: { email: "example-email@example.com" countryCode: FR } lines: [ { quantity: 2, merchandiseId: "gid://shopify/ProductVariant/1" } ] }) { cart { buyerIdentity { countryCode email phone } estimatedCost { totalAmount { amount currencyCode } } lines(first: 10) { edges { node { quantity estimatedCost { compareAtAmount { amount currencyCode } amount { amount currencyCode } } } } } } } } ``` ```json { "data": { "cartCreate": { "cart": { "buyerIdentity": { "countryCode": "FR", "email": "example-email@example.com", "phone": null }, "estimatedCost": { "totalAmount": { "amount": "150.0", "currencyCode": "EUR" } }, "lines": { "edges": [ { "node": { "quantity": 2, "estimatedCost": { "compareAtAmount": { "amount": "60.0", "currencyCode": "EUR" }, "amount": { "amount": "50.0", "currencyCode": "EUR" } } } } ] } } } } } } ``` ## Next steps - Learn how to [create and update a cart](/docs/storefronts/headless/building-with-the-storefront-api/cart/manage) in Shopify with the Storefront API. - Learn how to [manage subscription products](/docs/storefronts/headless/building-with-the-storefront-api/products-collections/subscriptions) by querying selling plans and selling plans groups with the Storefront API. - Learn how to [manage customer accounts](/docs/storefronts/headless/building-with-the-customer-account-api/customer-accounts) with the Storefront API. - [Retrieve metafields](/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields) with the Storefront API to access additional information from different types of resources. - Support [multiple languages](/docs/storefronts/headless/building-with-the-storefront-api/markets/multiple-languages) on a storefront with the Storefront API.