---
title: Contextual queries
description: >-
  Learn about using the GraphQL inContext directive to provide context for your
  queries or mutations
source_url:
  html: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/in-context
  md: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/in-context.md
api_name: storefront
---

# Contextual queries

***

## Requirements

* Your app can make [requests](https://shopify.dev/docs/api/storefront) to the GraphQL Storefront API.

***

## Using the @in​Context directive

The `@inContext` [directive](#appendix-graphql-directives) 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](#contextual-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.

***

## Cart 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](https://shopify.dev/docs/api/storefront/latest/mutations/cartbuyeridentityupdate) or during [cartCreate](https://shopify.dev/docs/api/storefront/latest/mutations/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.

***

## Contextual arguments

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

### Country

Apply an optional [country code argument](https://shopify.dev/api/storefront/latest/enums/countrycode). This example shows how to retrieve a list of available countries and their corresponding currencies for a shop located in France.

```gql
@inContext(country: FR)
```

* [Examples for localized pricing](https://shopify.dev/api/examples/international-pricing)

### Subdivision

Apply an optional [subdivision code argument](https://shopify.dev/docs/api/storefront/unstable/scalars/SubdivisionCode) together with `country` to resolve a [subdivision market](https://shopify.dev/docs/apps/build/markets/subdivision-markets) for the query.

```gql
@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.

### Language

Apply an optional [language code argument](https://shopify.dev/api/storefront/latest/enums/LanguageCode). This example shows how to return a product's `title`, `description`, and `options` translated into Spanish.

```gql
@inContext(language: ES)
```

* [Examples for supporting multiple languages](https://shopify.dev/api/examples/multiple-languages)
* Supported from version `2022-04` and later.

### Buyer Identity

Contextualize any query with an optional [buyer argument](https://shopify.dev/api/storefront/latest/input-objects/BuyerInput). This example shows how to return a product's price `amount` contextualized for a business customer buyer.

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

* [Example for supporting a contextualized buyer identity](https://shopify.dev/custom-storefronts/headless/b2b#step-3-contextualize-storefront-api-requests)
* **NOTE**: `customerAccessToken` is required, `companyLocationId` is optional.
* Supported from version `2024-04` and later.

### Visitor 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`](https://shopify.dev/docs/api/storefront/latest/objects/Cart#field-Cart.fields.checkoutUrl) to ensure privacy compliance throughout the checkout process. All consent fields are optional.

* [Examples for collecting and passing visitor consent with Checkout Kit](https://shopify.dev/docs/storefronts/mobile/checkout-kit/privacy-compliance)
* Supported from version `2025-10` and later.

### Channel

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

```gql
@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.

***

## Response `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.

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

***

## Appendix: Graph​QL directives

A GraphQL [directive](https://graphql.org/learn/queries/#directives) 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](https://shopify.dev/docs/api/storefront/latest#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](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/defer).

***