Commerce Layer JS SDK

A JavaScript Library wrapper that makes it quick and easy to interact with the Commerce Layer API.

What is Commerce Layer?

Commerce Layer is a headless platform that lets you easily build enterprise-grade ecommerce into any website, by using the language, CMS, and tools you already master and love.

Getting started

To get started with Commerce Layer JS SDK you need to install it and then get the credentials that will allow you to perform your API calls.

• Installation
• Authentication
• Import

Installation

Commerce Layer JS SDK is available as an npm package:

// npm
npm install @commercelayer/js-sdk

// yarn
yarn add @commercelayer/js-sdk

Authentication

All requests to Commerce Layer API must be authenticated with an OAuth2 bearer token. Hence, before starting to use this SDK you need to get a valid access token. Check our documentation for more information about the available authorization flows.

Feel free to use Commerce Layer JS Auth, a JavaScript library that helps you wrap our authentication API.

Import

You can use either the ES6 default or named import with the SDK as follow:

import CLayer from '@commercelayer/js-sdk'

CLayer.init({
  accessToken: 'your-access-token',
  endpoint: 'https://yourdomain.commercelayer.io'
})

// or

import { initCLayer, Sku, ShippingCategory } from '@commercelayer/js-sdk'

initCLayer({
  accessToken: 'your-access-token',
  endpoint: 'https://yourdomain.commercelayer.io'
})

In the following examples, we will use the latter solution (named import) and define only the functions associated with the specific resources we're going to access (SKUs and shipping categories). Check our API reference for the complete list of available resources and their attributes.

Usage

The code snippets below show how to use the Commerce Layer JS SDK when performing the standard CRUD operations provided by our REST API on the SKU resource.

• Create

  • How to create an SKU

• Retrieve

  • How to fetch a single SKU
  • How to fetch a collection of SKUs
  • How to paginate a collection of SKUs
  • How to iterate through a collection of SKUs
  • How to build complex queries

• Update

  • How to update an existing SKU

• Delete

  • How to delete an existing SKU

Create

How to create an SKU

  const shippingCategory = await ShippingCategory.findBy({ name: 'Merchandising'}) // selects the shipping category (it's a required relationship for the SKU resource)

  const attributes = {
    code: 'TSHIRTMM000000FFFFFFXL',
    name: 'Black Men T-shirt with White Logo (XL)',
    imageUrl: 'https://img.yourdomain.com/skus/image.png', // optional attribute
    shippingCategory: shippingCategory // assigns the relationship
  }

  const newSku = await Sku.create(attributes)

Check our API reference for more information on how to create an SKU.

Retrieve

How to fetch a single SKU

  // Fetches the SKU by ID
  const sku = await Sku.find('xYZkjABcde')

  // Fetches the SKU by code
  const sku = await Sku.findBy({ code: 'TSHIRTMM000000FFFFFFXLXX'})

  // Fetches the first SKU of the list
  const sku = await Sku.first()

  // Fetches the last SKU of the list
  const sku = await Sku.last()

When fetching a single resource you can leverage the mode() method to get its meta information:

  const sku = await Sku.find('xYZkjABcde')
  const meta = sku.mode() // the resource environment (can be one of 'test' or 'live')

Check our API reference for more information on how to retrieve an SKU.

How to fetch a collection of SKUs

  // LISTING RESULTS

  // Fetches all the SKUs
  const skus = await Sku.all()

  // Fetches the first 5 SKUs of the list
  const skus = await Sku.first(5)

  // Fetches the last 5 SKUs of the list
  const skus = await Sku.last(5)

  // SORTING RESULTS

  // Sorts the results by creation date in ascending order (default)
  const skus = await Sku.order({ createdAt: 'asc' }).all()

  // Sorts the results by creation date in descending order
  const skus = await Sku.order({ createdAt: 'desc' }).all()

  // INCLUDING ASSOCIATIONS

  // Includes an association (prices)
  const skus = await Sku.includes('prices').all()

  // Includes an association (prices) and fetches the realted currently loaded collection
  const sku = await Sku.includes('prices').first()
  const prices = sku.prices().target()

  // Includes an association (prices) and fetches the realted currently loaded collection as an array
  const sku = await Sku.includes('prices').first()
  const prices = sku.prices().toArray()

  // Includes an association (prices) and checks if the related currently loaded collection is empty or not
  const sku = await Sku.includes('prices').first()
  const isPricesEmpty = sku.prices().empty() // boolean

  // Includes an association (prices) and calculates the size of the related currently loaded collection
  const sku = await Sku.includes('prices').first()
  const pricesSize = sku.prices().size()

  // SPARSE FIELDSETS

  // Requests the API to return only specific fields
  const skus = await Sku.select('name', 'metadata').all()

  // Requests the API to return only specific fields of the included resource
  const skus = await Sku.includes('prices')
		.select('code', { prices: ['currencyCode', 'formattedAmount'] })
		.all()

  // FILTERING DATA

  // Filters all the SKUs fetching only the ones whose code starts with the string "TSHIRT"
  const skus = await Sku.where({ codeStart: 'TSHIRT'}).all()

  // Filters all the SKUs fetching only the ones whose code ends with the string "XLXX"
  const skus = await Sku.where({ codeEnd: 'XLXX'}).all()

  // Filters all the SKUs fetching only the ones whose name contains the string "White Logo"
  const skus = await Sku.where({ nameCont: 'White Logo'}).all()

  // Filters all the SKUs fetching only the ones created between two specific dates
  const skus = await Sku.where({ createdAtGt: '2018-01-01', createdAtLt: '2018-01-31'}).all() // filters combined according to an AND logic

  // Filters all the SKUs fetching only the ones created or updated after a specific date
  const skus = await Sku.where({ updatedAtOrCreatedAtGt: '2019-10-10' }).all() // attributes combined according to an OR logic

  // Filters all the SKUs fetching only the ones whose name contains the string "Black" and whose shipping category name starts with the string "MERCH"
  const skus = await Sku.where({ nameCont: 'Black', shippingCategoryNameStart: 'MERCH'}).all()

When fetching a collection of resources you can leverage the getMetaInfo() method to get its meta information:

  const skus = await Sku.all()
  const meta = skus.getMetaInfo()

Check our API reference for more information on how to list all SKUs, sort the results, use sparse fieldsets, include associations, and filter data.

How to paginate a collection of SKUs

When you fetch a collection of resources, you get paginated results:

  // Fetches the SKUs, setting the page number to 3 and the page size to 5
  const skus = await Sku.perPage(5).page(3).all()

  // Checks next page
  if(skus.hasNextPage()) {
    const nextSkus = await skus.nextPage()
    // ...
  }

  // Checks previous page
  if(skus.hasPrevPage()) {
    const prevSkus = await skus.prevPage()
    // ...
  }

  // Gets the total number of SKUs in the collection
  const skuCount = skus.recordCount()

  // Gets the total number of pages
  const pageCount = skus.pageCount()

The default page number is 1. The default page size is 10. The maximum page size allowed is 25.

Check our API reference for more information on how pagination works.

How to iterate through a collection of SKUs

To execute a function for every item of a collection, use the map() method:

  // Fetches the whole list of SKUs and prints their names and codes to console
  const skus = await Sku.all()
  skus.map(p => console.log('Product: ' + p.name + ' - Code: ' + p.code))

How to build complex queries

Commerce Layer SDK lets you construct API requests through simple to use chained relation methods. This means that all the methods above can be combined to create queries of greater complexity:

  // Requests the API to return only specific fields of the first 15 SKUs of the list (5 per page)
  const skus = await Sku.select('name', 'metadata').perPage(5).first(15)

  // Fetches the last 20 SKUs whose code start with the string "TSHIRT" (5 per page), including an association (prices)
  const skus = await Sku.where({ codeStart: 'TSHIRT'}).includes('prices').perPage(5).last(20)

Update

How to update an existing SKU

  const sku = await Sku.find('xYZkjABcde') // fetches the SKU by ID

  const attributes = {
    description: 'Updated description.',
    imageUrl: 'https://img.yourdomain.com/skus/new-image.png'
  }

  sku.update(attributes) // updates the SKU on the server

Check our API reference for more information on how to update an SKU.

Delete

How to delete an existing SKU

  const sku = await Sku.find('xYZkjABcde') // fetches the SKU by ID

  sku.destroy() // persisted deletion

Check our API reference for more information on how to delete an SKU.

Advanced features

Upon its basic usage, Commerce Layer JS SDK offers some specific functionalities you can leverage to handle when dealing with errors, performance, and more. The most useful are listed here below (more to come):

• Overriding credentials
• Handling validation errors
• Avoiding web application performance issues

Overriding credentials

If needed, Commerce Layer JS SDK lets you set the configuration at a request level. To do that, just use the withCredentials() method and authenticate the API call with the desired credentials:

  const skus = await Sku.withCredentials({
    accessToken: 'your-access-token',
    endpoint: 'https://yourdomain.commercelayer.io'
  }).all()

Handling validation errors

Commerce Layer API returns specific errors (with extra information) on each attribute of a single resource. You can inspect them to properly handle validation errors (if any). To do that, use the errors() method:

  // logs 2 error messages to console:
  // 'shipping_category - must exist'
  // 'name - can't be blank'

  const attributes = { code: 'TSHIRTMM000000FFFFFFXL' }

  const newSku = await Sku.create(attributes, (sku) => {
    const errors = sku.errors()
    if (!errors.empty()) {
      errors.toArray().map((e) => {
        console.error(e.code + ' on ' + e.field + ': ' + e.message)
      })
    }
  })

  // logs 1 error message to console
  // 'pieces_per_pack - must be greater than 0'

  const sku = await Sku.findBy({ code: 'TSHIRTMM000000FFFFFFXL' })

  const attributes = { piecesPerPack: 0 }

  sku.update(attributes, (sku) => {
    const errors = sku.errors()
    if (!errors.empty()) {
      errors.toArray().map((e) => {
      console.error(e.code + ' on ' + e.field + ': ' + e.message)
      })
    }
  })

Check our API reference for more information about the errors returned by the API.

Avoiding web application performance issues

Commerce Layer JS SDK is based on the ORM technique and returns collections of resources. If not managed appropriately, you could get some performance and memory issues. To avoid that, you can use it in the raw-response mode. This way, you'll get native JSON objects with all their attributes as the response from our API.

How to set the raw response globally

The raw-response mode can be easily activated globally by setting the rawResponse key to true in the options attribute of the init function, as follows:

import CLayer from '@commercelayer/js-sdk'

CLayer.init({
  accessToken: 'your-access-token',
  endpoint: 'https://yourdomain.commercelayer.io',
  options: {
    rawResponse: true
  }
})

If the raw-response mode is activated globally, you cannot access the ORM resource methods.

How to set the raw response for a single request

Alternatively, the raw response option can be managed at a single request level.

Create

In case of POST request methods you can directly set the rawResponse key to true, as follows:

const newSku = await Sku.create(attributes, { rawResponse: true }) // creates a new SKU

Retrieve

In case of GET request methods you can directly set the rawResponse key to true, as follows:

const sku = await Sku.find('xYZkjABcde', { rawResponse: true }) // fetches the SKU by ID

Update

In case of PATCH request methods, first you need to call the build function and then set the rawResponse key to true on the update, as follows:

const sku = Sku.build({ id: 'xYZkjABcde'}) // creates the related collection
await sku.update({ reference: 'REF-1'}, null, { rawResponse: true }) // updates the SKU reference

---

License

This repository is published under the MIT license.