shopify-api-node

Shopify API Node.js (Official module)

Official 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 - Required - A plain JavaScript object that contains the configuration options.

Options

• shopName - Required - A string that specifies the shop name. The shop's "myshopify.com" domain is also accepted.
• apiKey - Required for private apps - A string that specifies the API key of the app. This option must be used in conjunction with the password option and is mutually exclusive with the accessToken option.
• password - Required for private apps - A string that specifies the private app password. This option must be used in conjunction with the apiKey option and is mutually exclusive with the accessToken option.
• accessToken - Required for public apps - A string representing the permanent OAuth 2.0 access token. This option is mutually exclusive with the apiKey and password options. If you are looking for a premade solution to obtain an access token, take a look at the shopify-token module.
• apiVersion - Optional - A string to specify the Shopify API version to use for requests
• autoLimit - Optional - This option allows you to regulate the request rate in order to avoid hitting the rate limit. Requests are limited using the token bucket algorithm. Accepted values are a boolean or a plain JavaScript object. When using an object, the calls property and the interval property specify the refill rate and the bucketSize property the bucket size. For example { calls: 2, interval: 1000, bucketSize: 35 } specifies a limit of 2 requests per second with a burst of 35 requests. When set to true requests are limited as specified in the above example. Defaults to false.
• timeout - Optional - The number of milliseconds before the request times out. If the request takes longer than timeout, it will be aborted. Defaults to 60000, or 1 minute.

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,
    value_type: 'integer',
    namespace: 'inventory',
    owner_resource: 'product',
    owner_id: 632910392
  })
  .then((metafield) => console.log(metafield), (err) => console.error(err));

Available resources and methods

• accessScope
  • list()
• apiPermission
  • delete()
• applicationCharge
  • activate(id[, params])
  • create(params)
  • get(id[, params])
  • list([params])
• applicationCredit
  • create(params)
  • get(id[, params])
  • list([params])
• article
  • authors()
  • count(blogId[, params])
  • create(blogId, params)
  • delete(blogId, id)
  • get(blogId, id[, params])
  • list(blogId[, params])
  • tags([blogId][, params])
  • update(blogId, id, params)
• asset
  • create(themeId, params)
  • delete(themeId, params)
  • get(themeId, params)
  • list(themeId[, params])
  • update(themeId, params)
• balance
  • list()
  • transactions([params])
• blog
  • count()
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• carrierService
  • create(params)
  • delete(id)
  • get(id)
  • list()
  • update(id, params)
• checkout
  • complete(token)
  • count([params])
  • create(params)
  • get(token)
  • list([params])
  • shippingRates(token)
  • update(token, params)
• collect
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
• collectionListing
  • get(id)
  • list([params])
  • productIds(id[, params])
• comment
  • approve(id)
  • count([params])
  • create(params)
  • get(id[, params])
  • list([params])
  • notSpam(id)
  • remove(id)
  • restore(id)
  • spam(id)
  • update(id, params)
• country
  • count()
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• currency
  • list()
• customCollection
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• customer
  • accountActivationUrl(id)
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • orders(id)
  • search(params)
  • sendInvite(id[, params])
  • update(id, params)
• customerAddress
  • create(customerId, params)
  • default(customerId, id)
  • delete(customerId, id)
  • get(customerId, id)
  • list(customerId[, params])
  • set(customerId, params)
  • update(customerId, id, params)
• customerSavedSearch
  • count([params])
  • create(params)
  • customers(id[, params])
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• discountCode
  • create(priceRuleId, params)
  • delete(priceRuleId, id)
  • get(priceRuleId, id)
  • list(priceRuleId)
  • lookup(params)
  • update(priceRuleId, id, params)
• dispute
  • get(id)
  • list([params])
• draftOrder
  • complete(id[, params])
  • count()
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • sendInvoice(id[, params])
  • update(id, params)
• event
  • count([params])
  • get(id[, params])
  • list([params])
• fulfillment
  • cancel(orderId, id)
  • complete(orderId, id)
  • count(orderId[, params)
  • create(orderId, params)
  • get(orderId, id[, params])
  • list(orderId[, params])
  • open(orderId, id)
  • update(orderId, id, params)
• fulfillmentEvent
  • create(orderId, fulfillmentId, params)
  • delete(orderId, fulfillmentId, id)
  • get(orderId, fulfillmentId, id)
  • list(orderId, fulfillmentId[, params])
  • update(orderId, fulfillmentId, id, params)
• fulfillmentService
  • create(params)
  • delete(id)
  • get(id)
  • list([params])
  • update(id, params)
• giftCard
  • count([params])
  • create(params)
  • disable(id)
  • get(id)
  • list([params])
  • search(params)
  • update(id, params)
• giftCardAdjustment
  • create(giftCardId, params)
  • get(giftCardId, id)
  • list(giftCardId)
• inventoryItem
  • get(id)
  • list(params)
  • update(id, params)
• inventoryLevel
  • adjust(params)
  • connect(params)
  • delete(params)
  • list(params)
  • set(params)
• location
  • count
  • get(id)
  • inventoryLevels(id[, params])
  • list()
• marketingEvent
  • count()
  • create(params)
  • delete(id)
  • get(id)
  • list([params])
  • update(id, params)
  • engagements(id, params)
• metafield
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• order
  • cancel(id[, params])
  • close(id)
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • open(id)
  • update(id, params)
• orderRisk
  • create(orderId, params)
  • delete(orderId, id)
  • get(orderId, id)
  • list(orderId)
  • update(orderId, id, params)
• page
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• payment
  • count(checkoutToken)
  • create(checkoutToken, params)
  • get(checkoutToken, id)
  • list(checkoutToken)
• payout
  • get(id)
  • list([params])
• policy
  • list([params])
• priceRule
  • create(params)
  • delete(id)
  • get(id)
  • list([params])
  • update(id, params)
• product
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• productImage
  • count(productId[, params])
  • create(productId, params)
  • delete(productId, id)
  • get(productId, id[, params])
  • list(productId[, params])
  • update(productId, id, params)
• productListing
  • count()
  • create(productId[, params])
  • delete(productId)
  • get(productId)
  • list([params])
  • productIds([params])
• productVariant
  • count(productId)
  • create(productId, params)
  • delete(productId, id)
  • get(id[, params])
  • list(productId[, params])
  • update(id, params)
• province
  • count(countryId[, params])
  • get(countryId, id[, params])
  • list(countryId[, params])
  • update(countryId, id, params)
• recurringApplicationCharge
  • activate(id, params)
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • customize(id, params)
• redirect
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• refund
  • calculate(orderId, params)
  • create(orderId, params)
  • get(orderId, id[, params])
  • list(orderId[, params])
• report
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• resourceFeedback
  • create(params)
  • list()
• scriptTag
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• shippingZone
  • list([params])
• shop
  • get([params])
• smartCollection
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • order(id, params)
  • products(id[, params])
  • update(id, params)
• storefrontAccessToken
  • create(params)
  • delete(id)
  • list()
• tenderTransaction
  • list([params])
• theme
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)
• transaction
  • count(orderId)
  • create(orderId, params)
  • get(orderId, id[, params])
  • list(orderId[, params])
• usageCharge
  • create(recurringApplicationChargeId, params)
  • get(recurringApplicationChargeId, id[, params])
  • list(recurringApplicationChargeId[, params])
• user
  • current()
  • get(id)
  • list()
• webhook
  • count([params])
  • create(params)
  • delete(id)
  • get(id[, params])
  • list([params])
  • update(id, params)

where params is a plain JavaScript object. See https://help.shopify.com/api/reference?ref=microapps 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));

Become a master of the Shopify ecosystem by:

• Becoming a Shopify App Developer
• Checking out the roots
• Talking To Other Masters
• Reading API Docs
• Learning from others

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

Polaris

Shopify Apps already using Shopify API node:

(add yours!)

• Sample Node Express app by Shopify
• Wholesaler
• Wholesaler & Customer Pricing
• Wholesaler PRO
• Youtube Traffic

Supported by:

microapps

Used in our live products: MoonMail & MONEI

License

MIT