Skip to main content

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.

Anchor to RequirementsRequirements

Anchor to Step 1: Make queriesStep 1: Make queries

You can use the Storefront API to make the following queries:

Anchor to Query available countries and currenciesQuery 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.

Anchor to @inContext directive@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)).

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query @inContext(country: FR) {
localization {
availableCountries {
currency {
isoCode
name
symbol
}
isoCode
name
unitSystem
}
country {
currency {
isoCode
name
symbol
}
isoCode
name
unitSystem
}
}
}

JSON response

{
"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"
}
}
}
}

Anchor to Query product pricesQuery 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query allProducts @inContext(country: CA) {
products(first: 1) {
edges {
node {
variants(first: 1) {
edges {
node {
price {
amount
currencyCode
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"products": {
"edges": [
{
"node": {
"variants": {
"edges": [
{
"node": {
"price": {
"amount": "30.0",
"currencyCode": "CAD"
}
}
}
]
}
}
}
]
}
}
}

Anchor to Query price ranges for productsQuery price ranges for products

To query the price ranges 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).

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

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 response

{
"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"
}
}
}
}
]
}
}
}

Anchor to Query customer ordersQuery 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:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

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 response

{
"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"
}
}
}
}
]
}
}
}
]
}
}
}
}

Anchor to Step 2: Create a cartStep 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

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 response

{
"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"
}
}
}
}
]
}
}
}
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?