Skip to main content

Contextual queries

Anchor to RequirementsRequirements

  • Your app can make requests to the GraphQL Storefront API.

Anchor to Using the @inContext directiveUsing the @inContext directive

The @inContext directive allows clients to contextualize the GraphQL query with additional information. This context will be applied to the entire query and all its subfields.

With the arguments available you can:

  • Show pricing in a specific currency for a given country.
  • Return a product's price amount contextualized for a business customer buyer.
  • Translate product information to one of the shop's available languages.
  • Pass visitor consent information to prefill preferences in checkout.

Anchor to Cart queries and mutationsCart queries and mutations

Note

In Cart queries and mutations the buyer and country arguments for @inContext are ignored. In order to get a contextualized cart, set a buyer identity with cartBuyerIdentityUpdate or during cartCreate.

Other arguments (language, visitorConsent) will still apply on cart queries.

Anchor to Contextual argumentsContextual arguments

  • The Storefront API supports the contextual arguments listed below.
  • All are optional and can be applied in any combination.

Anchor to CountryCountry

Apply an optional country code argument. This example shows how to retrieve a list of available countries and their corresponding currencies for a shop located in France.

@inContext(country: FR)

Anchor to LanguageLanguage

Apply an optional language code argument. This example shows how to return a product's title, description, and options translated into Spanish.

@inContext(language: ES)

Anchor to Buyer IdentityBuyer Identity

Contextualize any query with an optional buyer argument. This example shows how to return a product's price amount contextualized for a business customer buyer.

@inContext(buyer: {customerAccessToken: 'token', companyLocationId: 'gid://shopify/CompanyLocation/1'})

Anchor to Visitor consentVisitor consent

Apply visitor consent information using an optional visitorConsent argument.

This example shows how to create a cart with visitor consent preferences @inContext(visitorConsent: {analytics: true, preferences: true, marketing: false, saleOfData: false}). The consent information is automatically encoded and included in the resulting checkoutUrl to ensure privacy compliance throughout the checkout process. All consent fields are optional.

Anchor to Response ,[object Object], extensionResponse context extension

When any contextual argument is set, you'll see a context appended to the extensions in the GQL response. It reveals the country and language code that was applied to the query.

"extensions": {
"context": {
"country": "CA",
"language": "EN"
}
}

Anchor to Appendix: GraphQL directivesAppendix: GraphQL directives

A GraphQL 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.

The Storefront API currently supports two directives:

  • @inContext: Allows clients to provide contextual information to the query or mutation (see above).
  • @defer: Allows clients to prioritize part of a GraphQL query without having to make more requests to fetch the remaining information. Learn more about prioritizing data in your query.
Was this page helpful?