---
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
---

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

***

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

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

***

## 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)

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

***

## 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).

***