Admin API Client

The Admin API Client library is for developers who want to interact with Shopify's Admin API. The features of this library are designed to be lightweight and minimally opinionated.

npm install @shopify/admin-api-client -s

• GraphQL Client
• REST Client

GraphQL Client

Getting Started

Initialize the client:

1import {createAdminApiClient} from '@shopify/admin-api-client';
2
3const client = createAdminApiClient({
4  storeDomain: 'your-shop-name.myshopify.com',
5  apiVersion: '2023-04',
6  accessToken: 'your-admin-api-access-token',
7});

Query for a product:

1const operation = `
2  query ProductQuery($id: ID!) {
3    product(id: $id) {
4      id
5      title
6      handle
7    }
8  }
9`;
10
11const {data, errors, extensions} = await client.request(operation, {
12  variables: {
13    id: 'gid://shopify/Product/7608002183224',
14  },
15});

[!NOTE] If you want to query the Admin REST API, you can use the REST client instead.

createAdminApiClient() parameters

Client properties

AdminApiClientConfig properties

ApiClientRequestOptions properties

ClientResponse<TData>

ResponseErrors

Client request() response examples

1{
2  "data": {
3    "product": {
4      "id": "gid://shopify/Product/7608002183224",
5      "title": "Aera",
6      "handle": "aera-helmet"
7    }
8  },
9  "extensions": {
10    "cost": {
11      "requestedQueryCost": 1,
12      "actualQueryCost": 1,
13      "throttleStatus": {
14        "maximumAvailable": 1000.0,
15        "currentlyAvailable": 999,
16        "restoreRate": 50.0
17      }
18    }
19  }
20}

1{
2  "networkStatusCode": 401,
3  "message": "Unauthorized"
4}

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

Usage examples

Query for a product

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

Dynamically set the Admin API version per data fetch

1const productQuery = `
2  query ProductQuery($id: ID!) {
3    product(id: $id) {
4      id
5      title
6      handle
7    }
8  }
9`;
10
11const {data, errors, extensions} = await client.request(productQuery, {
12  variables: {
13    id: 'gid://shopify/Product/7608002183224',
14  },
15  apiVersion: '2023-01',
16});

Add custom headers to API request

1const productQuery = `
2  query ProductQuery($id: ID!) {
3    product(id: $id) {
4      id
5      title
6      handle
7    }
8  }
9`;
10
11const {data, errors, extensions} = await client.request(productQuery, {
12  variables: {
13    id: 'gid://shopify/Product/7608002183224',
14  },
15  headers: {
16    'X-GraphQL-Cost-Include-Fields': true,
17  },
18});

Using client.fetch() to get API data

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

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});

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/admin-graphql-direct-proxy',
   5  documents: ['*.ts', '!node_modules'],
   6  projects: {
   7    default: shopifyApiProject({
   8      apiType: ApiType.Admin,
   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/admin.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.

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.

RequestParams

REST Client

Getting Started

Initialize the client:

1import {createAdminRestApiClient} from '@shopify/admin-api-client';
2
3const client = createAdminRestApiClient({
4  storeDomain: 'your-shop-name.myshopify.com',
5  apiVersion: '2023-04',
6  accessToken: 'your-admin-api-access-token',
7});

Query for a product:

1const response = await client.get('products/1234567890');
2
3if (response.ok) {
4  const body = await response.json();
5}

createAdminRestApiClient() parameters

Client properties

GetRequestOptions properties

PostRequestOptions properties

Same options as for GET requests, but data isn't optional.

PutRequestOptions properties

Same options as for POST requests.

DeleteRequestOptions properties

Same options as for GET requests.

Usage examples

Query for a product

1const response = await client.get('products/1234567890');
2
3if (response.ok) {
4  const body = await response.json();
5}

Update a product

1const response = await client.put('products/1234567890', {
2  data: {
3    product: {
4      handle: 'my-new-handle',
5    },
6  },
7});
8
9if (response.ok) {
10  const body = await response.json();
11}

Dynamically set the Admin API version per data fetch

1const response = await client.get('products/1234567890', {
2  apiVersion: '2023-01',
3});
4
5if (response.ok) {
6  const body = await response.json();
7}

Add custom headers to API request

1const response = await client.get('products/1234567890', {
2  headers: {
3    'X-My-Custom-Header': '1',
4  },
5});
6
7if (response.ok) {
8  const body = await response.json();
9}

Dynamically set the number of retries per request

1const response = await client.get('products/1234567890', {
2  retries: 2,
3});
4
5if (response.ok) {
6  const body = await response.json();
7}