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.
  • Resolve a subdivision market, such as a state, province, or prefecture.
  • Retrieve channel context data for a product.

Anchor to Cart queries and mutationsCart queries and mutations

Note

For cart queries and mutations, @inContext applies until a buyer identity is present on the cart. After a buyer identity is set with cartBuyerIdentityUpdate or during cartCreate, the buyer identity takes precedence. Conflicting @inContext values, such as country, are ignored.

Other arguments (language, visitorConsent, channelId) keep applying on cart queries and mutations.

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 SubdivisionSubdivision

Apply an optional subdivision code argument together with country to resolve a subdivision market for the query.

@inContext(country: CA, subdivision: "ON")
  • The subdivision argument requires the country argument.
  • The subdivision must belong to the given country. Otherwise, the query returns an error indicating that the subdivision isn't valid for that country.
  • The subdivision applies only when the shop has an enabled subdivision market that targets it. Otherwise, the subdivision argument is ignored and country-level context applies.
  • Supported on the unstable version only.

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 ChannelChannel

Channel context determines channel-scoped data, such as which products and collections are published to the requesting storefront.

@inContext(channelId: "gid://shopify/Channel/1")
  • The channel must belong to the same store and the same app as the credentials used for the request. Otherwise, the query returns a Channel not found for the given id. error.
  • Channel context also applies to cart queries and mutations.
  • Supported from version 2026-10 and later.

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?