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 multi-market commerce API and order management system that lets you add global shopping capabilities to any website, mobile app, chatbot, wearable, voice, or IoT device, with ease. Compose your stack with the best-of-breed tools you already mastered and love. Make any experience shoppable, anywhere, through a blazing-fast, enterprise-grade, and secure API.

Table of contents

• Getting started
• Installation
• Authentication
• Import
• Options
• SDK usage
• Overriding credentials
• Handling validation errors
• Using interceptors
• Refreshing access token
• Contributors guide
• Need help?
• License

Getting started

To get started with Commerce Layer JS SDK you need to install it, get the credentials that will allow you to perform your API calls, and import the SDK into your application's code. The sections below explain how to achieve this.

If you want, you can also read this tutorial from Commerce Layer's blog.

Installation

Commerce Layer JS SDK is available as an npm and yarn package that you can install with the command below:

1npm install @commercelayer/sdk
2
3// or
4
5yarn add @commercelayer/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. Kindly 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 the ES6 default import with the SDK like so:

1import CommerceLayer from '@commercelayer/sdk'
2
3const cl = CommerceLayer({
4  organization: 'your-organization-slug',
5  accessToken: 'your-access-token'
6})

Options

When instantiating a new SDK client you can pass some options to initialize it:

1{
2  organization: string        // The organization slug
3  accessToken: string         // A valid API access token
4  timeout?: number            // A custom request timout (<= 15 secs [default])
5  headers?: RequestHeaders    // Custom request headers
6  userAgent?: string          // Custom user-agent useful in certaing contexts but often not allowed by browsers
7  fetch?: Fetch               // A specific fetch implementation 
8  refreshToken?: RefreshToken // A function responsible for token refresh
9}

Same options can be changed after SDK initialization or passed at runtime while executing an API call:

1  const options = { ... }
2
3  // Instantiate the client using desired options
4  const cl = CommerceLayer(options)
5
6  // Change configuration after client cteation
7  cl.config(options)
8
9  // Use runtime configuration without persisting settings
10  cl.customers.list({}, options)

SDK usage

The JavaScript SDK is a wrapper around Commerce Layer API which means you would still be making API requests but with a different syntax. For now, we don't have comprehensive SDK documentation for every single resource our API supports (about 400+ endpoints), hence you will need to rely on our comprehensive API Reference as you go about using this SDK. So for example, if you want to create an order, take a look at the Order object or the Create an order documentation to see the required attributes and/or relationships. The same goes for every other supported resource.

To show you how things work, we will use the SKUs and Shipping Categories resource in the following examples. The code snippets below show how to use the SDK when performing the standard CRUD operations provided by our REST API. Kindly check our API reference for the complete list of available resources and their attributes.

Create

1  // Select the shipping category (it's a required relationship for the SKU resource)
2  const shippingCategories = await cl.shipping_categories.list({ filters: { name_eq: 'Merchandising' } })
3
4  const attributes = {
5    code: 'TSHIRTMM000000FFFFFFXL',
6    name: 'Black Men T-shirt with White Logo (XL)',
7    description: "A very beautiful and cozy mens t-shirt",
8    weight: "500",
9    unit_of_weight: "gr"
10    shipping_category: cl.shipping_categories.relationship(shippingCategories[0].id), // assigns the relationship
11  }
12
13  const newSku = await cl.skus.create(attributes)

Retrieve / List

1  // Fetch the SKU by ID
2  const sku = await cl.skus.retrieve('BxAkSVqKEn')
3
4  // Fetch all SKUs and filter by code
5  const sku = await cl.skus.list({ filters: { code_eq: 'TSHIRTMM000000FFFFFFXLXX' } })
6
7  // Fetch the first SKU of the list
8  const sku = (await cl.skus.list()).first()
9
10  // Fetch the last SKU of the list
11  const sku = (await cl.skus.list()).last()

1  // Fetch all the SKUs
2  const skus = await cl.skus.list()

1  const skus = await cl.skus.list()
2  const meta = skus.meta

1  // Sort the results by creation date in ascending order (default)
2  const skus = await cl.skus.list({ sort: { created_at: 'asc' } })
3
4  // Sort the results by creation date in descending order
5  const skus = await cl.skus.list({ sort: { created_at: 'desc' } })

1  // Include an association (prices)
2  const skus = await cl.skus.list({ include: [ 'prices' ] })
3
4  // Include an association (stock items)
5  const skus = await cl.skus.list({ include: [ 'stock_items' ] })

1  // Request the API to return only specific fields
2  const skus = await cl.skus.list({ fields: { skus: [ 'name', 'metadata' ] } })
3
4  // Request the API to return only specific fields of the included resource
5  const skus = await cl.skus.list({ include: [ 'prices' ], fields: { prices: [ 'currency_code', 'formatted_amount' ] } })

1  // Filter all the SKUs fetching only the ones whose code starts with the string "TSHIRT"
2  const skus = await cl.skus.list({ filters: { code_start: 'TSHIRT' } })
3
4  // Filter all the SKUs fetching only the ones whose code ends with the string "XLXX"
5  const skus = await cl.skus.list({ filters: { code_end: 'XLXX' } })
6
7  // Filter all the SKUs fetching only the ones whose name contains the string "White Logo"
8  const skus = await cl.skus.list({ filters: { name_cont: 'White Logo' } })
9
10  // Filter all the SKUs fetching only the ones created between two specific dates
11  // (filters combined according to the AND logic)
12  const skus = await cl.skus.list({ filters: { created_at_gt: '2018-01-01', created_at_lt: '2018-01-31'} })
13
14  // Filters all the SKUs fetching only the ones created or updated after a specific date
15  // (attributes combined according to the OR logic)
16  const skus = await cl.skus.list({ filters: { updated_at_or_created_at_gt: '2019-10-10' } })
17
18  // Filters all the SKUs fetching only the ones whose name contains the string "Black"
19  // and whose shipping category name starts with the string "MERCH"
20  const skus = await cl.skus.list({ filters: { name_cont: 'Black', shipping_category_name_start: 'MERCH'} })

1  // Fetch the SKUs, setting the page number to 3 and the page size to 5
2  const skus = await cl.skus.list({ pageNumber: 3, pageSize: 5 })
3
4  // Get the total number of SKUs in the collection
5  const skuCount = skus.meta.recordCount
6
7  // Get the total number of pages
8  const pageCount = skus.meta.pageCount

1  // Fetch the whole list of SKUs (1st page) and print their names and codes to console
2  const skus = await cl.skus.list()
3  skus.map(p => console.log('Product: ' + p.name + ' - Code: ' + p.code))

1// Fetch 1-to-1 related resource: billing address of an order
2const billingAddress = await cl.orders.billing_address('xYZkjABcde')
3
4// Fetch 1-to-N related resources: orders associated to a customer
5const orders = await cl.customers.orders('XyzKjAbCDe', { fields: ['status', 'number'] })

1// Get the total number of placed orders
2const placedOrders = await cl.orders.count({ filters: { status_eq: 'placed' } })
3

Update

1  const sku = {
2    id: 'xYZkjABcde',
3    description: 'Updated description...',
4    imageUrl: 'https://img.yourdomain.com/skus/new-image.png'
5  }
6
7  cl.skus.update(sku) // updates the SKU on the server

Delete

1  cl.skus.delete('xYZkjABcde') // persisted deletion

Overriding credentials

If needed, Commerce Layer JS SDK lets you change the client configuration and set it at a request level. To do that, just use the config() method or pass the options parameter and authenticate the API call with the desired credentials:

1  // Permanently change configuration at client level
2  cl.config({ organization: 'you-organization-slug', accessToken: 'your-access-token' })
3  const skus = await cl.skus.list()
4
5  or
6
7  // Use configuration at request level
8  cl.skus.list({}, { organization: 'you-organization-slug', accessToken: 'your-access-token' })

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 attribute of the catched error:

1  // Log error messages to console:
2  const attributes = { code: 'TSHIRTMM000000FFFFFFXL', name: '' }
3
4  const newSku = await cl.skus.create(attributes).catch(error => console.log(error.errors))
5
6  // Logged errors
7  /*
8  [
9    {
10      title: "can't be blank",
11      detail: "name - can't be blank",
12      code: 'VALIDATION_ERROR',
13      source: { pointer: '/data/attributes/name' },
14      status: '422',
15      meta: { error: 'blank' }
16    },
17    {
18      title: 'has already been taken',
19      detail: 'code - has already been taken',
20      code: 'VALIDATION_ERROR',
21      source: { pointer: '/data/attributes/code' },
22      status: '422',
23      meta: { error: 'taken', value: 'TSHIRTMM000000FFFFFFXL' }
24    },
25    {
26      title: "can't be blank",
27      detail: "shipping_category - can't be blank",
28      code: 'VALIDATION_ERROR',
29      source: { pointer: '/data/relationships/shipping_category' },
30      status: '422',
31      meta: { error: 'blank' }
32    }
33  ]
34  */
35

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

Using interceptors

You can use interceptors to intercept SDK messages and modify them on the fly before the request is sent to the API or before the response is parsed and returned by the client. You can also access the error object before it is thrown by the SDK.

Interceptors are special functions that are able to handle SDK messages and return a (eventually) modified version of them for use by the client.

1  const requestInterceptor = (request: RequestObj): RequestObj => {
2    console.log(request)
3    return request
4  }
5
6  const responseInterceptor = (response: ResponseObj): ResponseObj => {
7    console.log(response)
8    return response
9  }
10
11  const errorInterceptor = (error: ErrorObj): ErrorObj => {
12    console.log(error)
13    return error
14  }

Here an example of how to use them:

1  // Add the interceptors (only one or all if needed)
2  cl.addRequestInterceptor(requestInterceptor)
3  cl.addResponseInterceptor(responseInterceptor, errorInterceptor)
4
5  const customers = await cl.customers.list()
6
7  // Remove interceptors
8  // Tt is possible to remove only a specific interceptor: cl.removeInterceptor('request')
9  cl.removeInterceptors()

Raw Response Reader

The RawResponseReader is a special interceptor that allows to catch the original message coming frome the API before it is parsed and translated in SDK objects.

1  // Add a RawResponseReader capable of capturing also response headers
2  const rrr = cl.addRawResponseReader({ headers: true })
3  
4  const customers = await cl.customers.list()
5
6  cl.removeRawResponseReader()
7
8  console.log(rrr.rawResponse)
9  console.log(rrr.headers)

Refreshing access token

It is possible that you are using an access token that is about to expire especially if it has been used for many API calls. In this case you can define a special function that takes care of refreshing the token when a call fails because it has expired.

1  async function myRefreshTokenFunction(espiredToken: string): Promise<string> {
2    // Get a new access token using for example our js-auth library
3    return (await getAccessToken()).accessToken
4  }
5
6  cl.config({ refreshToken: myRefreshTokenFunction })
7
8  // If needed you can later retrieve the new access token
9  const newToken = cl.currentAccessToken

Contributors guide

1. Fork this repository (learn how to do this here).

2. Clone the forked repository like so:

   1git clone https://github.com/<your username>/commercelayer-sdk.git && cd commercelayer-sdk

3. Make your changes and create a pull request (learn how to do this).

4. Someone will attend to your pull request and provide some feedback.

Need help?

• Join Commerce Layer's Discord community.
• Ping us on Bluesky, X (formerly Twitter), or LinkedIn.
• Is there a bug? Create an issue on this repository.

License

This repository is published under the MIT license.