Home

Awesome

Shopify API Node.js

Version npm Build Status Coverage Status

Shopify API bindings for Node.js.

Installation:

$ npm install --save shopify-api-node

API

This module exports a constructor function which takes an options object.

Shopify(options)

Creates a new Shopify instance.

Arguments

Options

Return value

A Shopify instance.

Exceptions

Throws an Error exception if the required options are missing.

Example

const Shopify = require('shopify-api-node');

const shopify = new Shopify({
  shopName: 'your-shop-name',
  apiKey: 'your-api-key',
  password: 'your-app-password'
});

shopify.callLimits

The callLimits property allows you to monitor the API call limit. The value is an object like this:

{
  remaining: 30,
  current: 10,
  max: 40
}

Values start at undefined and are updated every time a request is made. After every update the callLimits event is emitted with the updated limits as argument.

shopify.on('callLimits', (limits) => console.log(limits));

When using the GraphQL API, a different property is used to track the API call limit: callGraphqlLimits.

Keep in mind that the autoLimit option is ignored while using GraphQL API.

shopify.on('callGraphqlLimits', (limits) => console.log(limits));

Resources

Every resource is accessed via your shopify instance:

const shopify = new Shopify({
  shopName: 'your-shop-name',
  accessToken: 'your-oauth-token'
});

// shopify.<resource_name>.<method_name>

Each method returns a Promise that resolves with the result:

shopify.order
  .list({ limit: 5 })
  .then((orders) => console.log(orders))
  .catch((err) => console.error(err));

The Shopify API requires that you send a valid JSON string in the request body including the name of the resource. For example, the request body to create a country should be:

{
  "country": {
    "code": "FR",
    "tax": 0.25
  }
}

When using shopify-api-node you don't have to specify the full object but only the nested one as the module automatically wraps the provided data. Using the above example this translates to:

shopify.country
  .create({ code: 'FR', tax: 0.25 })
  .then((country) => console.log(country))
  .catch((err) => console.error(err));

Similarly, the Shopify API includes the resource name in the JSON string that is returned in the response body:

{
  "country": {
    "id": 1070231510,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}

shopify-api-node automatically unwraps the parsed object and returns:

{
  id: 1070231510,
  name: 'France',
  tax: 0.2,
  code: 'FR',
  tax_name: 'TVA',
  provinces: []
}

This behavior is valid for all resources.

Metafields

Shopify allows for adding metafields to various resources. You can use the owner_resource and owner_id properties to work with metafields that belong to a particular resource as shown in the examples below.

Get metafields that belong to a product:

shopify.metafield
  .list({
    metafield: { owner_resource: 'product', owner_id: 632910392 }
  })
  .then(
    (metafields) => console.log(metafields),
    (err) => console.error(err)
  );

Create a new metafield for a product:

shopify.metafield
  .create({
    key: 'warehouse',
    value: 25,
    type: 'integer',
    namespace: 'inventory',
    owner_resource: 'product',
    owner_id: 632910392
  })
  .then(
    (metafield) => console.log(metafield),
    (err) => console.error(err)
  );

Pagination

Pagination in API version 2019-07 and above can be done as shown in the following example:

(async () => {
  let params = { limit: 10 };

  do {
    const products = await shopify.product.list(params);

    console.log(products);

    params = products.nextPageParameters;
  } while (params !== undefined);
})().catch(console.error);

Each set of results may have the nextPageParameters and previousPageParameters properties. These properties specify respectively the parameters needed to fetch the next and previous page of results.

This feature is only available on version 2.24.0 and above.

Shopify rate limit avoidance

shopify-api-node has two optional mechanisms for avoiding requests failing with 429 Rate Limit Exceeded errors from Shopify.

The autoLimit option implements a client side leaky bucket algorithm for delaying requests until Shopify is likely to accept them. When autoLimit is on, each Shopify instance will track how many requests have been made, and delay sending subsequent requests if the rate limit has been exceeded. autoLimit is very efficient because it almost entirely avoids sending requests which will return 429 errors, but, it does not coordinate between multiple Shopify instances or across multiple processes. If you're using shopify-api-node in many different processes, autoLimit will not correctly avoid 429 errors.

The maxRetries option implements a retry based strategy for getting requests to Shopify, where when a 429 error occurs, the request is automatically retried after waiting. Shopify usually replies with a Retry-After header indicating to the client when the rate limit is available, and so shopify-api-node will wait that long before retrying. If you are using shopify-api-node in many different processes, they will all be competing to use the same rate limit shopify enforces, so there is no guarantee that retrying after the Retry-After header delay will work. It is recommended to set maxRetries to a high value like 10 if you are making many concurrent requests in many processes to ensure each request is retried for long enough to succeed.

autoLimit and maxRetries can't be used simultaneously. Both are off by default.

Available resources and methods

where params is a plain JavaScript object. See the Rest Admin API reference for parameters details.

GraphQL

The shopify instance also allows to use the GraphQL API through the graphql method, which returns a promise that resolves with the result data:

const shopify = new Shopify({
  shopName: 'your-shop-name',
  accessToken: 'your-oauth-token'
});

const query = `{
  customers(first: 5) {
    edges {
      node {
        displayName
        totalSpent
      }
    }
  }
}`;

shopify
  .graphql(query)
  .then((customers) => console.log(customers))
  .catch((err) => console.error(err));

Hooks

shopify-api-node supports being passed hooks which are called by got (the underlying HTTP library) during the request lifecycle.

For example, we can log every error that is encountered when using the maxRetries option:

const shopify = new Shopify({
  shopName: 'your-shop-name',
  accessToken: 'your-oauth-token',
  maxRetries: 3,
  // Pass the `beforeRetry` hook down to Got.
  hooks: {
    beforeRetry: [(options, error, retryCount) => console.error(error)]
  }
});

For more information on the available got hooks, see the got v11 hooks documentation.

Become a master of the Shopify ecosystem by:

Use Polaris, a React powered Frontend Framework which mimics the Shopify merchant admin:

Polaris

Shopify Apps already using Shopify API node:

(add yours!)

Supported by:

MONEI

License

MIT