Multiple currencies for custom storefronts

Merchants who use Shopify Payments can sell products and accept payments in multiple currencies. Prices are displayed in a customer's preferred currency on all storefront and checkout pages.

This guide covers how you can query the Storefront API to return the supported currencies for shops that are using multiple currencies. It also shows how you can query product variants to see their prices in the available currencies, and how to query products to see the maximum and minimum variant prices for a selected currency. The guide also explains how to create a checkout in a specific currency by providing the presentmentCurrencyCode property, and then querying and completing the checkout.

Prerequisites

This guide assumes that you have completed our Getting started with the Storefront API guide, and that you are authenticated with the API. The guide also assumes that you've created product variants in your test shop.

The code examples in this guide can be run in GraphiQL or your preferred API client.

Querying the shop for supported currencies

Shopify stores have a store currency, which is the default currency that's used to display prices on a storefront. Merchants can enable multiple presentment currencies from their Shopify Payments settings. Presentment currencies are the currencies that can be used to display prices to customers on a storefront and checkout.

You can query a shop's paymentSettings object to return a list of enabled presentment currencies:

query {
  shop {
    paymentSettings {
      countryCode
      currencyCode
      enabledPresentmentCurrencies
    }
  }
}

View response

JSON response

The query returns the following data object:

{
  "data": {
    "shop": {
      "paymentSettings": {
        "countryCode": "CA",
        "currencyCode": "USD",
        "enabledPresentmentCurrencies": [
          "AUD",
          "CAD",
          "EUR",
          "GBP",
          "JPY",
          "USD"
        ]
      }
    }
  }
}

Return presentment prices on a product variant

You can query specific product variants to return pricing information in different presentment currencies. By default all currencies are returned, or you can use the presentmentCurrencies argument as part of the presentmentPrices object to return a specific currency.

When merchants set sale prices for products, the price is the sales price and original price is the compare at price. The following query returns the compareAtPrice and price for the product variant's Australian (AUD) presentment currency:

query {
  node(id:"Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yNjY2OTIzNzM4Mg==") {
    ... on ProductVariant {
      id
      presentmentPrices(first:1, presentmentCurrencies: AUD) {
        edges {
          node {
            compareAtPrice {
              amount
              currencyCode
            }
            price {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
}

View response

JSON response

The query returns the following data object:

{
  "data": {
    "node": {
      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yNjY2OTIzNzM4Mg==",
      "presentmentPrices": {
        "edges": [
          {
            "node": {
              "compareAtPrice": null,
              "price": {
                "amount": "8.0",
                "currencyCode": "AUD"
              }
            }
          }
        ]
      }
    }
  }
}

Query products for the presentment price ranges

You can query products to return the range of variant prices for presentment currencies. To get a price in a specific presentment currency you can query Node for a given product variant.

You can return the presentmentPriceRanges by querying products. By default all currencies are returned, or you can use the presentmentCurrencies argument on presentmentPriceRanges to return a specific currency. The following query returns the presentmentPriceRanges for all of the store's supported currencies:

query {
  products(first:2) {
    edges {
      node {
        handle
        id
        presentmentPriceRanges(first: 5) {
          edges {
            node {
              maxVariantPrice {
                amount
                currencyCode
              }
              minVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

View response

JSON response

The query returns the following data object:

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "handle": "testproduct",
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg=",
            "presentmentPriceRanges": {
              "edges": [
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "8.0",
                      "currencyCode": "AUD"
                    },
                    "minVariantPrice": {
                      "amount": "2.0",
                      "currencyCode": "AUD"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "7.0",
                      "currencyCode": "CAD"
                    },
                    "minVariantPrice": {
                      "amount": "2.0",
                      "currencyCode": "CAD"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "4.95",
                      "currencyCode": "EUR"
                    },
                    "minVariantPrice": {
                      "amount": "0.95",
                      "currencyCode": "EUR"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "5.0",
                      "currencyCode": "GBP"
                    },
                    "minVariantPrice": {
                      "amount": "1.0",
                      "currencyCode": "GBP"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "600.0",
                      "currencyCode": "JPY"
                    },
                    "minVariantPrice": {
                      "amount": "200.0",
                      "currencyCode": "JPY"
                    }
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "handle": "blue-silk-tuxedo",
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE1ODg0MzkxMjE5NzY=",
            "presentmentPriceRanges": {
              "edges": [
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "104.0",
                      "currencyCode": "AUD"
                    },
                    "minVariantPrice": {
                      "amount": "45.0",
                      "currencyCode": "AUD"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "94.0",
                      "currencyCode": "CAD"
                    },
                    "minVariantPrice": {
                      "amount": "41.0",
                      "currencyCode": "CAD"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "64.95",
                      "currencyCode": "EUR"
                    },
                    "minVariantPrice": {
                      "amount": "27.95",
                      "currencyCode": "EUR"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "58.0",
                      "currencyCode": "GBP"
                    },
                    "minVariantPrice": {
                      "amount": "25.0",
                      "currencyCode": "GBP"
                    }
                  }
                },
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "7700.0",
                      "currencyCode": "JPY"
                    },
                    "minVariantPrice": {
                      "amount": "3300.0",
                      "currencyCode": "JPY"
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

The following query only returns the presentmentPriceRanges for the AUD currency code:

query {
  products(first:2) {
    edges {
      node {
        handle
        id
        presentmentPriceRanges(first: 5, presentmentCurrencies: AUD) {
          edges {
            node {
              maxVariantPrice {
                amount
                currencyCode
              }
              minVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

View response

JSON response

The query returns the following data object:

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "handle": "testproduct",
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg=",
            "presentmentPriceRanges": {
              "edges": [
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "8.0",
                      "currencyCode": "AUD"
                    },
                    "minVariantPrice": {
                      "amount": "2.0",
                      "currencyCode": "AUD"
                    }
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "handle": "blue-silk-tuxedo",
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE1ODg0MzkxMjE5NzY=",
            "presentmentPriceRanges": {
              "edges": [
                {
                  "node": {
                    "maxVariantPrice": {
                      "amount": "105.0",
                      "currencyCode": "AUD"
                    },
                    "minVariantPrice": {
                      "amount": "45.0",
                      "currencyCode": "AUD"
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Creating a checkout by specifying the currency

An app can create checkouts using any of the enabled presentment currencies on a merchant's store.

To create a checkout using a specific currency, include the currency code as an input argument in the checkoutCreate mutation:

mutation {
  checkoutCreate(input: {
    lineItems: [{ variantId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yNjY2OTIzNzM4Mg==", quantity: 1 }]
  , email:"user@domain.com", presentmentCurrencyCode: AUD}) {
    checkout {
       id
       webUrl
      currencyCode
       lineItems(first: 5) {
         edges {
           node {
             title
             quantity
           }
         }
       }
    }
  }
}

View response

JSON response

If the mutation is valid, then the following response is returned including the currencyCode:

{
  "data": {
    "checkoutCreate": {
      "checkout": {
        "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wYjkwNzYyMGNjYjUwNjU0YjRjMzlmYTg2MzU0MWQ3Nj9rZXk9MDI2OTJmYjQyYTM5ZGQ0MmY1ZDk2MjhkN2VlN2RkMDg=",
        "webUrl": "https://domain.myshopify.com/14376108/checkouts/0b907620ccb50654b4c39fa863541d76?key=02692fb42a39dd42f5d9628d7ee7dd08",
        "currencyCode": "AUD",
        "lineItems": {
          "edges": [
            {
              "node": {
                "title": "testproduct updated title",
                "quantity": 1
              }
            }
          ]
        }
      }
    }
  }
}

Completing the checkout

When you complete a checkout, you can provide the currency code of the created checkout as an input argument on the checkoutCompleteWithCreditCardV2 mutation. This example uses the session ID from the Shopify card vault to complete the mutation. For a detailed guide on how to complete checkouts, see Creating a Checkout.

This guide assumes you've already queried the Shopify card vault to obtain the session ID.

To complete the payment, send the payment information, including the amount, currencyCode and billingAddress fields. Send the payment session ID as the vaultID. The following mutation completes the checkout using Australian currency by sending the AUD currency code as part of the payment object.

mutation checkoutCompleteWithCreditCardV2($checkoutId: ID!, $payment: CreditCardPaymentInputV2!) {
  checkoutCompleteWithCreditCardV2(checkoutId: $checkoutId, payment: $payment) {
    checkout {
      id
    }
    checkoutUserErrors {
      code
      field
      message
    }
    payment {
      id
    }
  }
}

GraphQL variables:

{
  "checkoutId": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wYjkwNzYyMGNjYjUwNjU0YjRjMzlmYTg2MzU0MWQ3Nj9rZXk9MDI2OTJmYjQyYTM5ZGQ0MmY1ZDk2MjhkN2VlN2RkMDg=",
  "payment": {
    "paymentAmount": {
      "amount": "35.94",
      "currencyCode": "AUD"
    },
    "idempotencyKey": "123",
    "billingAddress": {
      "firstName":  "John",
      "lastName": "Doe",
      "address1": "123 Test Street",
      "province": "Quebec",
      "country": "Canada",
      "city": "Montreal",
      "zip": "H3K0X2"
    },
    "vaultId": "west-1c193679df55009f08ce3baeba56f01f"
  }
}

View response

JSON response:

The response includes the payment ID of the completed checkout:

{
  "data": {
    "checkoutCompleteWithCreditCardV2": {
      "checkout": {
        "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC9hOGE0MWU4Y2I4MDU4YjdmOTI1MTcxZDUwMzhjYmZmMj9rZXk9ZTQ4NGFlNjdlZDE4MmYzN2Y0ODZkZjkxNDE1MDMyYTY="
      },
      "checkoutUserErrors": [],
      "payment": {
        "id": "Z2lkOi8vc2hvcGlmeS9QYXltZW50LzgwNTY3MDg3OTI4OD9jaGVja291dD1hOGE0MWU4Y2I4MDU4YjdmOTI1MTcxZDUwMzhjYmZmMiZrZXk9ZTQ4NGFlNjdlZDE4MmYzN2Y0ODZkZjkxNDE1MDMyYTY="
      }
    }
  }
}

Next steps

You might find the following resources useful if you want to know more about the concepts introduced in this guide:

Sign up for a Partner account to get started.

Sign up