npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@commercelayer/sdk

v8.0.5

Published

Commerce Layer Javascript SDK

Readme

Commerce Layer JS SDK

Version Downloads/week License Verify CodeQL TypeScript

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

This package is generated and released from the commercelayer-sdk monorepo, alongside @commercelayer/provisioning-sdk. Both are produced by the same generator from the API’s own published schema.

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

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:

npm install @commercelayer/sdk

// or

yarn 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

The SDK offers two import styles. The default entry is the bundled client — use it unless you have a specific reason not to. The selective (tree-shakeable) style lives on a separate subpath and carries an important caveat described below.

Bundled client (default)

import { CommerceLayer } from '@commercelayer/sdk'

const cl = CommerceLayer({
  accessToken: 'your-access-token',
  apiVersion: '2026-05'
})

const orderList = await cl.orders.list()
const skuList = await cl.skus.list()

All resource accessors are available directly on the client object. This increases your final bundle size, but every call is scoped to that specific client instance — so you can safely create and use multiple clients with different access tokens at the same time (multi-tenant apps, serverless with connection reuse, etc.):

const clUS = CommerceLayer({ accessToken: usToken, apiVersion: '2026-05' })
const clEU = CommerceLayer({ accessToken: euToken, apiVersion: '2026-05' })

const [usOrders, euOrders] = await Promise.all([
  clUS.orders.list(),
  clEU.orders.list()
]) // each request uses its own token

Selective resource imports (/single-client)

import { CommerceLayer, orders, skus } from '@commercelayer/sdk/single-client'

const cl = CommerceLayer({
  accessToken: 'your-access-token',
  apiVersion: '2026-05'
})

const orderList = await orders.list()
const skuList = await skus.list()

Only the imported resources are included in your bundle, so it produces the smallest output. The trade-off: imported resources share a single global SDK configuration. If two requests are in-flight simultaneously with different access tokens, they may silently use the wrong token — so this style supports only one active token at a time.

It is a good fit for edge/serverless functions or webhook handlers that use only a few resources and a single token. When you need multiple concurrent tokens, use the bundled client above.

Options

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

{
  organization?: string       // The organization slug
  accessToken: string         // A valid API access token
  apiVersion: ApiVersion      // The API version to target, e.g. '2026-05' — required, see API version below
  timeout?: number            // A custom request timout (<= 15 secs [default])
  headers?: RequestHeaders    // Custom request headers
  userAgent?: string          // Custom user-agent useful in certaing contexts but often not allowed by browsers
  fetch?: Fetch               // A specific fetch implementation 
  refreshToken?: RefreshToken // A function responsible for token refresh
}

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

  const options = { ... }

  // Instantiate the client using desired options
  const cl = CommerceLayer(options)

  // Change configuration after client cteation
  cl.config(options)

  // Use runtime configuration without persisting settings
  cl.customers.list({}, options)

API version

The Core API is versioned, and every request targets a single version. apiVersion is therefore required when creating a client, and becomes part of each request URL — /api/2026-05/orders.

Only the versions this release of the SDK was generated for are accepted; any other value is a type error. Both are exported:

import { API_SCHEMA_VERSION, API_SUPPORTED_VERSIONS } from '@commercelayer/sdk'

API_SUPPORTED_VERSIONS // ['2017-08', '2026-05'] — the versions you can target
API_SCHEMA_VERSION     // '2026-05' — the version the types describe

The types are generated for API_SCHEMA_VERSION. Resources and fields that exist only in an older version are still included, marked @deprecated with the last version that has them, and newer additions carry @since — so you can keep targeting '2017-08' while migrating, and your editor shows what changes.

The version can be changed on an existing client, or overridden for a single request:

cl.config({ apiVersion: '2017-08' })

const orderList = await cl.orders.list({}, { apiVersion: '2017-08' })

[!IMPORTANT] Upgrading from 7.x: apiVersion is new and required, so every CommerceLayer(...) call needs it.

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.

The examples below assume a client cl, created as shown in Import.

Create

  // Select the shipping category (it's a required relationship for the SKU resource)
  const shippingCategories = await cl.shipping_categories.list({ filters: { name_eq: 'Merchandising' } })

  // Attributes passed inline, so each value is checked against the field it sets
  const newSku = await cl.skus.create({
    code: 'TSHIRTMM000000FFFFFFXL',
    name: 'Black Men T-shirt with White Logo (XL)',
    description: 'A very beautiful and cozy mens t-shirt',
    weight: 500,
    unit_of_weight: 'gr',
    shipping_category: cl.shipping_categories.relationship(shippingCategories[0].id), // assigns the relationship
  })

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

Retrieve / List

  // Fetch the SKU by ID
  const sku = await cl.skus.retrieve('BxAkSVqKEn')

  // Fetch all SKUs and filter by code
  const skuList = await cl.skus.list({ filters: { code_eq: 'TSHIRTMM000000FFFFFFXLXX' } })

  // Fetch the first SKU of the list
  const skuList = (await cl.skus.list()).first()

  // Fetch the last SKU of the list
  const skuList = (await cl.skus.list()).last()

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

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

When fetching a collection of resources you can leverage the meta attribute to get its meta information like so:

  const skuList = await cl.skus.list()
  const meta = skuList.meta

ℹ️ Check our API reference for more information on how to list all SKUs.

  // Sort the results by creation date in ascending order (default)
  const skuList = await cl.skus.list({ sort: { created_at: 'asc' } })

  // Sort the results by creation date in descending order
  const skuList = await cl.skus.list({ sort: { created_at: 'desc' } })

ℹ️ Check our API reference for more information on how to sort results.

  // Include an association (prices)
  const skuList = await cl.skus.list({ include: [ 'prices' ] })

  // Include an association (stock items)
  const skuList = await cl.skus.list({ include: [ 'stock_items' ] })

ℹ️ Check our API reference for more information on how to include associations.

  // Request the API to return only specific fields
  const skuList = await cl.skus.list({ fields: { skus: [ 'name', 'metadata' ] } })

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

ℹ️ Check our API reference for more information on how to use sparse fieldsets.

  // Filter all the SKUs fetching only the ones whose code starts with the string "TSHIRT"
  const skuList = await cl.skus.list({ filters: { code_start: 'TSHIRT' } })

  // Filter all the SKUs fetching only the ones whose code ends with the string "XLXX"
  const skuList = await cl.skus.list({ filters: { code_end: 'XLXX' } })

  // Filter all the SKUs fetching only the ones whose name contains the string "White Logo"
  const skuList = await cl.skus.list({ filters: { name_cont: 'White Logo' } })

  // Filter all the SKUs fetching only the ones created between two specific dates
  // (filters combined according to the AND logic)
  const skuList = await cl.skus.list({ filters: { created_at_gt: '2018-01-01', created_at_lt: '2018-01-31'} })

  // Filters all the SKUs fetching only the ones created or updated after a specific date
  // (attributes combined according to the OR logic)
  const skuList = await cl.skus.list({ filters: { updated_at_or_created_at_gt: '2019-10-10' } })

  // 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 skuList = await cl.skus.list({ filters: { name_cont: 'Black', shipping_category_name_start: 'MERCH'} })

ℹ️ Check our API reference for more information on how to filter data.

When you fetch a collection of resources, you get paginated results. You can request specific pages or items in a page like so:

  // Fetch the SKUs, setting the page number to 3 and the page size to 5
  const skuList = await cl.skus.list({ pageNumber: 3, pageSize: 5 })

  // Get the total number of SKUs in the collection
  const skuCount = skuList.meta.recordCount

  // Get the total number of pages
  const pageCount = skuList.meta.pageCount

PS: the default page number is 1, the default page size is 10, and the maximum page size allowed is 25.

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

A few resources — such as event stores — use cursor-based pagination instead of page numbers. Navigate with pageAfter (and pageBefore), and read the cursor for the next page from meta.cursor, which is present only on cursor-paginated responses:

  const skuId = 'xYZkjABcde'

  // Event stores are fetched as a relationship of a resource
  let page = await cl.skus.event_stores(skuId, { pageSize: 10 })
  const events = [...page]

  // Follow the cursor until there are no more pages
  while (page.meta.cursor?.next) {
    page = await cl.skus.event_stores(skuId, { pageAfter: page.meta.cursor.next.after })
    events.push(...page)
  }

PS: the default page size is 10 and the maximum is 25. On cursor-paginated responses the offset fields (meta.pageCount/meta.recordCount) are NaN and hasNextPage() returns false, so check meta.cursor.next instead. The pageAfter/pageBefore params are always accepted at the type level; offset-paginated resources simply ignore them.

ℹ️ See the event stores pagination reference for details.

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

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

Many resources have relationships with other resources and instead of including these associations as seen above, you can fetch them directly. This way, in the case of 1-to-N relationships, you can filter or sort the resulting collection as standard resources.

// Fetch 1-to-1 related resource: billing address of an order
const billingAddress = await cl.orders.billing_address('xYZkjABcde')

// Fetch 1-to-N related resources: orders associated to a customer
const customerOrders = await cl.customers.orders('XyzKjAbCDe', { fields: ['status', 'number'] })

In general:

  • An API endpoint like /api/customers or /api/customers/<customerId> translates to cl.customers.list() or cl.customers.retrieve('<customerId>') with the SDK.
  • 1-to-1 relationship API endpoints like /api/orders/<orderId>/shipping_address translates to cl.orders.shipping_address('<orderId>') with the SDK, or to cl.orders.retrieve('<orderId>', { include: ['shipping_address'] }) to get it along with the order.
  • 1-to-N relationship API endpoints like /api/customers/<customerId>?include=orders or /api/customers/<customerId>/orders translates to cl.customers.retrieve('<customerId>', { include: ['orders'] }) or cl.customers.orders('<customerId>') with the SDK.

ℹ️ Check our API reference for more information on how to fetch relationships.

Many times you simply need to count how many resources exist with certain characteristics. You can then call the special count function passing a filter to get as result the total number of resources.

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

Update

  const sku = {
    id: 'xYZkjABcde',
    description: 'Updated description...',
    image_url: 'https://img.yourdomain.com/skus/new-image.png'
  }

  cl.skus.update(sku) // updates the SKU on the server

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

Delete

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

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

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:

  // Permanently change configuration at client level
  cl.config({ organization: 'you-organization-slug', accessToken: 'your-access-token' })
  const skuList = await cl.skus.list()

  // or

  // Use configuration at request level
  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:

  // Log error messages to console:
  const attributes = { code: 'TSHIRTMM000000FFFFFFXL', name: '' }

  const newSku = await cl.skus.create(attributes).catch(error => console.log(error.errors))

  // Logged errors
  /*
  [
    {
      title: "can't be blank",
      detail: "name - can't be blank",
      code: 'VALIDATION_ERROR',
      source: { pointer: '/data/attributes/name' },
      status: '422',
      meta: { error: 'blank' }
    },
    {
      title: 'has already been taken',
      detail: 'code - has already been taken',
      code: 'VALIDATION_ERROR',
      source: { pointer: '/data/attributes/code' },
      status: '422',
      meta: { error: 'taken', value: 'TSHIRTMM000000FFFFFFXL' }
    },
    {
      title: "can't be blank",
      detail: "shipping_category - can't be blank",
      code: 'VALIDATION_ERROR',
      source: { pointer: '/data/relationships/shipping_category' },
      status: '422',
      meta: { error: 'blank' }
    }
  ]
  */

ℹ️ 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.

  const requestInterceptor = (request: RequestObj): RequestObj => {
    console.log(request)
    return request
  }

  const responseInterceptor = (response: ResponseObj): ResponseObj => {
    console.log(response)
    return response
  }

  const errorInterceptor = (error: ErrorObj): ErrorObj => {
    console.log(error)
    return error
  }

Here an example of how to use them:

  // Add the interceptors (only one or all if needed)
  cl.addRequestInterceptor(requestInterceptor)
  cl.addResponseInterceptor(responseInterceptor, errorInterceptor)

  const customerList = await cl.customers.list()

  // Remove interceptors
  // Tt is possible to remove only a specific interceptor: cl.removeInterceptor('request')
  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.

  // Add a RawResponseReader capable of capturing also response headers
  const rrr = cl.addRawResponseReader({ headers: true })
  
  const customerList = await cl.customers.list()

  cl.removeRawResponseReader()

  console.log(rrr.rawResponse)
  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.

  async function myRefreshTokenFunction(espiredToken: string): Promise<string> {
    // Get a new access token using for example our js-auth library
    return (await getAccessToken()).accessToken
  }

  cl.config({ refreshToken: myRefreshTokenFunction })

  // If needed you can later retrieve the new access token
  const newToken = cl.currentAccessToken

Contributors guide

  1. Fork this repository (learn how to do this by reading the GitHub documentation).

  2. Clone the forked repository like so:

    git clone https://github.com/<your username>/commercelayer-sdk.git && cd commercelayer-sdk
  3. Install the workspace from the repository root:

    pnpm install
  4. Make your changes. Most of this package is generated from the API schema — anything you edit under gen/ will be overwritten. Change the generator or sdk.config.ts instead, then run pnpm generate and commit the result.

  5. Create a pull request (learn how to do this). Lint, types, both test suites and a check that generated output is reproducible run automatically.

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

Need help?

License

This repository is published under the MIT license.