shopify.clients.Graphql

January 17, 2024 · View on GitHub

Instances of this class can make requests to the Shopify Admin GraphQL API.

Note: You can use the Shopify Admin API GraphiQL explorer to help build your queries.

Constructor

Example

// Requests to /my-endpoint must be made with authenticatedFetch from App Bridge for embedded apps
app.get('/my-endpoint', async () => {
  const sessionId = await shopify.session.getCurrentId({
    isOnline: true,
    rawRequest: req,
    rawResponse: res,
  });

  // use sessionId to retrieve session from app's session storage
  // getSessionFromStorage() must be provided by application
  const session = await getSessionFromStorage(sessionId);

  const client = new shopify.clients.Graphql({
    session,
    apiVersion: ApiVersion.January23,
  });
});

Parameters

Receives an object containing:

session

Session | :exclamation: required

The Shopify Session containing an access token to the API.

apiVersion

ApiVersion

This will override the default API version. Any requests made by this client will reach this version instead.

Request

Sends a request to the Admin API.

Examples

Using a query string

const response = await client.request(
  `{
    products (first: 10) {
      edges {
        node {
          id
          title
          descriptionHtml
        }
      }
    }
  }`,
);
console.log(response.data, response.extensions);

Using variables

const response = await client.request(
  `query GetProducts($first: Int!) {
    products (first: $first) {
      edges {
        node {
          id
          title
          descriptionHtml
        }
      }
    }
  }`,
  {
    variables: {
      first: 10,
    },
  },
);
console.log(response.data, response.extensions);

Note: If using TypeScript, you can pass in a type argument for the response body:

// If using TypeScript, you can type the response body
interface MyResponseBodyType {
  data: {
    //...
  };
}

const response = await client.request<MyResponseBodyType>(/* ... */);

// response.body will be of type MyResponseBodyType
console.log(response.body.data);

Note: If there are any errors in the response, request will throw a GraphqlQueryError which includes details from the API response:

import {GraphqlQueryError} from '@shopify/shopify-api';

try {
  const products = await client.request(/* ... */);

  // No errors, proceed with logic
} catch (error) {
  if (error instanceof GraphqlQueryError) {
    // look at the GraphQL errors returned from the API response
    error.body?.errors.graphQLErrors
    // Also, error.headers contains the headers of the response received from Shopify
  } else {
    // handle other errors
  }
}