Storefront API Client

The Storefront API Client manages the API's authentication information and provides various methods that enables devs to interacts with the API.

Getting started

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

1yarn add @shopify/storefront-api-client

1npm install @shopify/storefront-api-client --s

1pnpm add @shopify/storefront-api-client

CDN

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

1// The minified `0.2.3` version of the Storefront API Client
2<script src="https://unpkg.com/@shopify/storefront-api-client@0.2.3/dist/umd/storefront-api-client.min.js"></script>
3
4<script>
5  const client = ShopifyStorefrontAPIClient.createStorefrontApiClient({...});
6</script>

Initialization

Public access token client initialization

1import {createStorefrontApiClient} from '@shopify/storefront-api-client';
2
3const client = createStorefrontApiClient({
4  storeDomain: 'http://your-shop-name.myshopify.com',
5  apiVersion: '2023-10',
6  publicAccessToken: 'your-storefront-public-access-token',
7});

Create a server enabled client using a private access token and a custom Fetch API

[!WARNING] Private Storefront API delegate access tokens should only be used in server-to-server implementations and not within a browser environment.

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.

1import {
2  createStorefrontApiClient,
3  CustomFetchApi,
4} from '@shopify/storefront-api-client';
5import {fetch as nodeFetch} from 'node-fetch';
6
7const client = createStorefrontApiClient({
8  storeDomain: 'http://your-shop-name.myshopify.com',
9  apiVersion: '2023-10',
10  privateAccessToken: 'your-storefront-private-access-token',
11  customFetchApi: nodeFetch,
12});

createStorefrontApiClient() parameters

Client properties

StorefrontApiClientConfig properties

ApiClientRequestOptions properties

ClientResponse<TData>

ClientStreamResponse<TData>

ResponseErrors

Client request() response examples

1{
2  "data": {
3    "product": {
4      "id": "gid://shopify/Product/12345678912",
5      "title": "Sample product # 1"
6    }
7  },
8  "extensions": {
9    "context": {
10      "country": "US",
11      "language": "EN"
12    }
13  }
14}

1{
2  "errors": {
3    "networkStatusCode": 401,
4    "message": ""
5  }
6}

1{
2  "errors": {
3    "networkStatusCode": 200,
4    "message": "An error occurred while fetching from the API. Review the `graphQLErrors` object for details.",
5    "graphQLErrors": [
6      {
7        "message": "Field 'testField' doesn't exist on type 'Product'",
8        "locations": [
9          {
10            "line": 17,
11            "column": 3
12          }
13        ],
14        "path": ["fragment ProductFragment", "testField"],
15        "extensions": {
16          "code": "undefinedField",
17          "typeName": "Product",
18          "fieldName": "testField"
19        }
20      }
21    ]
22  }
23}

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}

Create a localized cart

1const cartCreateMutation = `
2  mutation ($input: CartInput!, $country: CountryCode, $language: LanguageCode)
3  @inContext(country: $country, language: $language) {
4    cartCreate(input: $input) {
5      userErrors {
6        message
7        code
8        field
9      }
10      cart {
11        id
12        checkoutUrl
13      }
14    }
15  }
16`;
17
18const {data, errors, extensions} = await client.request(cartCreateMutation, {
19  variables: {
20    input: {},
21    country: 'JP',
22    language: 'JA',
23  },
24});

Query for shop information

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

Dynamically set the Storefront API version per 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  apiVersion: '2023-07',
16});

Add custom headers to 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});

Dynamically set the number of retries per 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  retries: 2,
16});

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}

Typing variables and return objects

This client is compatible with the @shopify/api-codegen-preset package. You can use that package to create types from your operations with the Codegen CLI.

There are different ways to configure codegen with it, but the simplest way is to:

1. Add the preset package as a dev dependency to your project, for example:

   1npm install --save-dev @shopify/api-codegen-preset

2. Create a .graphqlrc.ts file in your root containing:

   1import {ApiType, shopifyApiProject} from '@shopify/api-codegen-preset';
   2
   3export default {
   4  schema: 'https://shopify.dev/storefront-graphql-direct-proxy',
   5  documents: ['*.ts', '!node_modules'],
   6  projects: {
   7    default: shopifyApiProject({
   8      apiType: ApiType.Storefront,
   9      apiVersion: '2023-10',
   10      outputDir: './types',
   11    }),
   12  },
   13};

3. Add "graphql-codegen": "graphql-codegen" to your scripts section in package.json.

4. Tag your operations with #graphql, for example:

   1const {data, errors, extensions} = await client.request(
   2  `#graphql
   3  query Shop {
   4    shop {
   5      name
   6    }
   7  }`,
   8);
   9console.log(data?.shop.name);

5. Run npm run graphql-codegen to parse the types from your operations.

[!NOTE] Remember to ensure that your tsconfig includes the files under ./types!

Once the script runs, it'll create the file ./types/storefront.generated.d.ts. When TS includes that file, it'll automatically cause the client to detect the types for each query.

Log Content Types

UnsupportedApiVersionLog

This log content is sent to the logger whenever an unsupported API version is provided to the client.

HTTPResponseLog

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

HTTPRetryLog

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

RequestParams

Gotchas / Troubleshooting

URL validation errors when using React Native

If you're using this package in a React Native project, you might encounter URL validation errors when initializing the storefront api client. For example:

Error: Storefront API Client: a valid store domain ("http://shop.myshopify.com/") must be provided

To avoid issues:

1. Install the react-native-url-polyfill package:

1npm i react-native-url-polyfill

2. Add the following import to the top of your entry file, typically index.js:

1import 'react-native-url-polyfill/auto';

This will apply a global polyfill for the URL object, allowing you to instantiate the storefront api client without encountering URL validation errors.