GraphQL Client

The GraphQL Client can be used to interact with any Shopify's GraphQL APIs. Client users are expected to provide the full API URL and necessary headers.

Getting Started

Using your preferred package manager, install this package in a project:

1yarn add @shopify/graphql-client

1npm install @shopify/graphql-client --s

1pnpm add @shopify/graphql-client

CDN

The UMD builds of each release version are available via the unpkg CDN

1// The minified `v0.9.3` version of the GraphQL API Client
2<script src="https://unpkg.com/@shopify/graphql-client@0.9.3/dist/umd/graphql-client.min.js"></script>
3
4<script>
5const client = ShopifyGraphQLClient.createGraphQLClient({...});
6</script>

Client initialization

1import {createGraphQLClient} from '@shopify/graphql-client';
2
3const client = createGraphQLClient({
4  url: 'http://your-shop-name.myshopify.com/api/2023-10/graphql.json',
5  headers: {
6    'Content-Type': 'application/json',
7    'X-Shopify-Storefront-Access-Token': 'public-token',
8  },
9  retries: 1
10});

Create a server enabled client using a custom Fetch API

In order to use the client within a server, a server enabled JS Fetch API will need to be provided to the client at initialization. By default, the client uses window.fetch for network requests.

1import {createGraphQLClient} from '@shopify/graphql-client';
2import {fetch as nodeFetch} from 'node-fetch';
3
4const client = createGraphQLClient({
5  url: 'http://your-shop-name.myshopify.com/api/2023-10/graphql.json',
6  headers: {
7    'Content-Type': 'application/json',
8    'X-Shopify-Storefront-Access-Token': 'public-token',
9  },
10  customFetchApi: nodeFetch
11});

createGraphQLClient() parameters

Property	Type	Description
url	string	The GraphQL API URL
headers	Record<string, string | string[]>	Headers to be included in requests
retries?	number	The number of HTTP request retries if the request was abandoned or the server responded with a Too Many Requests (429) or Service Unavailable (503) response. Default value is 0. Maximum value is 3.
customFetchApi?	(url: string, init?: {method?: string, headers?: HeaderInit, body?: string}) => Promise<Response>	A replacement fetch function that will be used in all client network requests. By default, the client uses window.fetch().
logger?	(logContent: HTTPResponseLog|HTTPRetryLog|HTTPResponseGraphQLDeprecationNotice) => void	A logger function that accepts log content objects. This logger will be called in certain conditions with contextual information.

Client properties

Property	Type	Description
config	{url: string, headers: Record<string, string | string[]>, retries: number}	Configuration for the client
fetch	(operation: string, options?: RequestOptions) => Promise<Response>	Fetches data from the GraphQL API using the provided GQL operation string and RequestOptions object and returns the network response
request	<TData>(operation: string, options?: RequestOptions) => Promise<ClientResponse<TData>>	Fetches data from the GraphQL API using the provided GQL operation string and RequestOptions object and returns a normalized response object
requestStream	<TData>(operation: string, options?: RequestOptions) => Promise <AsyncIterator<ClientStreamResponse<TData>>>	Fetches GQL operations that can result in a streamed response from the API (eg. Storefront API's @defer directive). The function returns an async iterator and the iterator will return normalized stream response objects as data becomes available through the stream.

RequestOptions properties

Name	Type	Description
variables?	Record<string, any>	Variable values needed in the graphQL operation
url?	string	Alternative request API URL
headers?	Record<string, string | string[]>	Additional and/or replacement headers to be used in the request
retries?	number	Alternative number of retries for the request. Retries only occur for requests that were abandoned or if the server responds with a Too Many Request (429) or Service Unavailable (503) response. Minimum value is 0 and maximum value is 3.
keepalive?	boolean	Whether to keep a connection alive when page is unloaded before a request has completed. Default value is false.
signal?	AbortSignal	If this option is set, the request can be canceled by calling abort() on the corresponding AbortController.

ClientResponse<TData>

Name	Type	Description
data?	TData | any	Data returned from the GraphQL API. If TData was provided to the function, the return type is TData, else it returns type any.
errors?	ResponseErrors	Errors object that contains any API or network errors that occured while fetching the data from the API. It does not include any UserErrors.
extensions?	Record<string, any>	Additional information on the GraphQL response data and context. It can include the context object that contains the context settings used to generate the returned API response.

ClientStreamResponse<TData>

Name	Type	Description
data?	TData | any	Currently available data returned from the GraphQL API. If TData was provided to the function, the return type is TData, else it returns type any.
errors?	ResponseErrors	Errors object that contains any API or network errors that occured while fetching the data from the API. It does not include any UserErrors.
extensions?	Record<string, any>	Additional information on the GraphQL response data and context. It can include the context object that contains the context settings used to generate the returned API response.
hasNext	boolean	Flag to indicate whether the response stream has more incoming data

ResponseErrors

Name	Type	Description
networkStatusCode?	number	HTTP response status code
message?	string	The provided error message
graphQLErrors?	any[]	The GraphQL API errors returned by the server
response?	Response	The raw response object from the network fetch call

Usage examples

Query for a product

1const productQuery = `
2  query ProductQuery($handle: String) {
3    product(handle: $handle) {
4      id
5      title
6      handle
7    }
8  }
9`;
10
11const {data, errors, extensions} = await client.request(productQuery, {
12  variables: {
13    handle: 'sample-product',
14  },
15});

Query for product info using the @defer directive

1const productQuery = `
2  query ProductQuery($handle: String) {
3    product(handle: $handle) {
4      id
5      handle
6      ... @defer(label: "deferredFields") {
7        title
8        description
9      }
10    }
11  }
12`;
13
14const responseStream = await client.requestStream(productQuery, {
15  variables: {handle: 'sample-product'},
16});
17
18// await available data from the async iterator
19for await (const response of responseStream) {
20  const {data, errors, extensions, hasNext} = response;
21}

Add additional custom headers to the API request

1const productQuery = `
2  query ProductQuery($handle: String) {
3    product(handle: $handle) {
4      id
5      title
6      handle
7    }
8  }
9`;
10
11const {data, errors, extensions} = await client.request(productQuery, {
12  variables: {
13    handle: 'sample-product',
14  },
15  headers: {
16    'Shopify-Storefront-Id': 'shop-id',
17  },
18});

Use an updated API URL in the API request

1const productQuery = `
2  query ProductQuery($handle: String) {
3    product(handle: $handle) {
4      id
5      title
6      handle
7    }
8  }
9`;
10
11const {data, errors, extensions} = await client.request(productQuery, {
12  variables: {
13    handle: 'sample-product',
14  },
15  url: 'http://your-shop-name.myshopify.com/api/unstable/graphql.json',
16});

Set a custom retries value in the API request

1const shopQuery = `
2  query ShopQuery {
3    shop {
4      name
5      id
6    }
7  }
8`;
9
10// Will retry the HTTP request to the server 2 times if the requests were abandoned or the server responded with a 429 or 503 error
11const {data, errors, extensions} = await client.request(shopQuery, {
12  retries: 2,
13});

Make a request that should run even if page is unloaded

1const shopQuery = `
2  query ShopQuery {
3    shop {
4      name
5      id
6    }
7  }
8`;
9
10const {data, errors, extensions} = await client.request(shopQuery, {
11  keepalive: true,
12});

Provide GQL query type to client.request() and client.requestStream()

1import {print} from 'graphql/language';
2
3// GQL operation types are usually auto generated during the application build
4import {CollectionQuery, CollectionDeferredQuery} from 'types/appTypes';
5import collectionQuery from './collectionQuery.graphql';
6import collectionDeferredQuery from './collectionDeferredQuery.graphql';
7
8const {data, errors, extensions} = await client.request<CollectionQuery>(
9  print(collectionQuery),
10  {
11    variables: {
12      handle: 'sample-collection',
13    },
14  }
15);
16
17const responseStream = await client.requestStream<CollectionDeferredQuery>(
18  print(collectionDeferredQuery),
19  {
20    variables: {handle: 'sample-collection'},
21  }
22);

Using client.fetch() to get API data

1const shopQuery = `
2  query shop {
3    shop {
4      name
5      id
6    }
7  }
8`;
9
10const response = await client.fetch(shopQuery);
11
12if (response.ok) {
13  const {errors, data, extensions} = await response.json();
14}

Log Content Types

HTTPResponseLog

This log content is sent to the logger whenever a HTTP response is received by the client.

Property	Type	Description
type	LogType['HTTP-Response']	The type of log content. Is always set to HTTP-Response
content	{requestParams: [url, init?], response: Response}	Contextual data regarding the request and received response

HTTPRetryLog

This log content is sent to the logger whenever the client attempts to retry HTTP requests.

Property	Type	Description
type	LogType['HTTP-Retry']	The type of log content. Is always set to HTTP-Retry
content	{requestParams: [url, init?], lastResponse?: Response, retryAttempt: number, maxRetries: number}	Contextual data regarding the upcoming retry attempt. requestParams: parameters used in the request lastResponse: previous response retryAttempt: the current retry attempt count maxRetries: the maximum number of retries

HTTPResponseGraphQLDeprecationNotice

This log content is sent to the logger whenever a HTTP response with a X-Shopify-API-Deprecated-Reason is received by the client.

Property	Type	Description
type	LogType['HTTP-Response-GraphQL-Deprecation-Notice']	The type of log content. Is always set to HTTP-Response-GraphQL-Deprecation-Notice
content	{requestParams: [url, init?], deprecationNotice: string}	Contextual data regarding the request and received deprecation information

RequestParams

Property	Type	Description
url	string	Requested URL
init?	{method?: string, headers?: HeaderInit, body?: string}	The request information