Commerce Layer SDK Utils

A JavaScript Library that makes even more easier to interact with Commerce Layer API using the official JavaScript SDK.

Installation and usage

SDK v8.x (requires ^8.0.0)

The Core API is versioned, so SDK v8 requires apiVersion when creating the client. The default entry of @commercelayer/sdk is the bundled client, which carries every resource: pass it to CommerceLayerUtils and all of them are available to the utilities.

import { CommerceLayer } from "@commercelayer/sdk"
import CommerceLayerUtils, { executeBatch } from '@commercelayer/sdk-utils'

const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
CommerceLayerUtils(cl)

await executeBatch(batch)

To take advantage of tree shaking, use the single client from @commercelayer/sdk/single-client and pass only the resources you really need.

import { CommerceLayer, orders, customers } from "@commercelayer/sdk/single-client"
import CommerceLayerUtils, { retrieveAll } from '@commercelayer/sdk-utils'

const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
CommerceLayerUtils(cl, [ orders, customers ])

const customerList = await retrieveAll<Customer>('customers')

Resources can also be added later to the CommerceLayerUtils configuration.

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

const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
const utilsConfig = CommerceLayerUtils(cl)

utilsConfig.addApiResources(orders, customers)
utilsConfig.addApiResource(skus)

[!NOTE] With the single client, a utility can only use the resources that were passed to CommerceLayerUtils: calling retrieveAll('skus') without adding skus throws Resource [skus] not available.

SDK v7.x

Use @commercelayer/sdk-utils 4.x (requires ^7.11.0).

Table of functions and utilities

Common functions

• executeBatch - execute a list of prepared API requests
• retrieveAll - fetch all existing resources
• updateAll - apply changes to a set of resources
• deleteAll - delete a set of resources
• retrievePage - retrieve a custom page of resources

Cleanups

• splitCleanup - split a large cleanup in multiple small cleanups
• executeCleanup - split a large cleanup in multiple small cleanups and execute them
• cleanupsToBatchTasks - translate a list of cleanups in executable batch tasks

Exports

• splitExport - split a large export in multiple small exports
• executeExport - split a large export in multiple small exports and execute them
• exportsToBatchTasks - translate a list of exports in executable batch tasks

Imports

• splitImport - split a large import in multiple small imports
• executeImport - split a large import in multiple small imports and execute them
• importsToBatchTasks - translate a list of imports in executable batch tasks

Webhooks

• denormalizePayload - parse a webhook payload and transform it in the appropriate SDK object

SDK query helpers

• IncludeHelper - build an includeobject to use in query filters
• FilterHelper - build a filter object to use in query filters

Common functions

executeBatch

This function allows to prepare and then execute a number of API calls without having to worry about current rate limits.

for (const emailAddress of emailList) {
    const task: Task = {
      resourceType: "customers",
      operation: "create",
      resource: { email: emailAddress } as CustomerCreate,
      onSuccess: { callback: sendEmail },
      onFailure: { errorHandler: handleError }
    }
    tasks.push(task)
  }

  const batch: Batch = {
    tasks,
    options: { refreshToken: refreshAccessToken }
  }


await executeBatch(batch)

In the example above the onSuccess and onFailure callbacks have been used to handle the task result in case of success or failure of the execution.

It's also possible to fill the resource attributes taking values from the result of the previous batch step. In the following example we are updating a resource taking its id from a previous retrieve or create task:

const task: Task = {
    resourceType: "customers",
    operation: "update",
    prepareResource: (res: TaskResourceParam, last: TaskResourceResult): TaskResourceParam => {
        return {
          ...res,
          id: last.id,
          reference: 'new-reference'
        }
      }
  }

retrieveAll

This function allows to fetch all existing resources of a specific type executing all necessary API requests respecting current API rate limits. The limit option can be used to retrieve only a limited number of resources.

const skus = await retrieveAll<Sku>('skus', { limit: 100 })

updateAll

This function allows to modify a set of resources of a specific type, using a filter to identify them.

const skuData = { reference_origin: 'legacy-system-0' }

const filters = { created_at_lt: '2023-01-01' }

const updateResult = await updateAll('skus', skuData, { filters })

deleteAll

This function allows to delete a set of resources of a specific type, using a filter to identify them.

const filters = { created_at_lt: '2023-01-01', reference_origin_eq: 'legacy-system-0' }

const deleteResult = await deleteAll('skus', { filters })

retrievePage

This function allows to fetch a specific subset of resources defining page attributes that are not permitted by the API and using all the standard common filters. An error will be thrown if the page parameters are not compatible with the number of existing resources.

 const skus = await retrievePage<Sku>('skus', { pageNumber: 16, pageSize: 139, sort: ['code'] })

Cleanups

splitCleanup

Split cleanup in multiple cleanups respecting the maximum limit of resources included

const clp: CleanupCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const splitClp: CleanupCreate[] = await splitCleanup(clp)

executeCleanup

Split cleanup in multiple cleanups respecting the maximum limit of resources included and execute them

const clp: CleanupCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const execClp: CleanupResult[] = await executeCleanup(clp)

cleanupsToBatchTasks

Convert a list of cleanups generated by splitCleanup to a list of tasks that can be executed by the function executeBatch

const clps = await splitCleanup(clp)

const tasks = cleanupsToBatchTasks(clps)

Exports

splitExport

Split an export in multiple exports respecting the maximum limit of resources included

const exp: ExportCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const splitExp: ExportCreate[] = await splitExport(exp)

executeExport

Split an export in multiple exports respecting the maximum limit of resources included and execute them

const exp: ExportCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const execExp: ExportResult[] = await executeExport(exp)

exportsToBatchTasks

Convert a list of exports generated by splitExport to a list of tasks that can be executed by the function executeBatch

const exps = await splitExport(exp)

const tasks = exportsToBatchTasks(exps)

Imports

splitImport

Split an import in multiple imports respecting the maximum limit of inputs included

const exp: ImportCreate = {
 resource_type: 'customers',
 inputs: [
  { ... },
  { ... },
  ...
  { ... }
 ]
}

const splitImp: ImportCreate[] = await splitImport(imp)

executeImport

Split an import in multiple imports respecting the maximum limit of inputs included and execute them

const exp: ImportCreate = {
 resource_type: 'customers',
 inputs: [
  { ... },
  { ... },
  ...
  { ... }
 ]
}

const execImp: ImportResult[] = await executeImport(imp)

importsToBatchTasks

Convert a list of imports generated by splitImport to a list of tasks that can be executed by the function executeBatch

const imps = await splitImport(imp)

const tasks = importsToBatchTasks(imps)

Webhooks

denormalizePayload

This function takes in input the payload of a webhook in JSON format and transform it in the appropriate typed resource to be used with the official Typescript SDK.

const shipment = denormalizePayload<Shipment>(webhookPayload)

SDK query helpers

IncludeHelper

This helper can be used to easily build the array of included resources to use in SDK query parameters.

Note: The versions resource has been removed from the Commerce Layer API and is no longer available in the include helper.

Standard include

const include: QueryInclude = [ 'market', 'customer', 'customer.customer_group' ]

Include with IncludeHelper

import { Include } from '@commercelayer/sdk-utils'

const include: QueryInclude = [ Include.orders.market.build(), Include.orders.customer.build(), Include.orders.customer.customer_group.build() ]

// The same as above but using a single instance of the orders helper
const io = Include.orders
const includeSingle: QueryInclude = [ io.market.build(), io.customer.build(), io.customer.customer_group.build() ]

Include using buildInclude function

import { buildInclude } from '@commercelayer/sdk-utils'

const include: QueryInclude = buildInclude(Include.orders.market, Include.orders.customer, Include.orders.customer.customer_group)

Add resources to include to an existing query filter

import { Include } from '@commercelayer/sdk-utils'

const queryFilter: QueryParams = {}

const io = Include.orders

io.market.addTo(queryFilter)
io.customer.addTo(queryFilter)
io.customer.customer_group.addTo(queryFilter)

FilterHelper

This helper can be used to easily build the object containing the filter predicates to use in SDK query parameters.

Note: The versions resource has been removed from the Commerce Layer API and is no longer available in the filter helper.

Standard filter

const filter: QueryFilter = {
  number_eq: '123',
  market_reference_eq: 'MKT',
  reference_or_customer_customer_group_reference_eq: 'REF',
  status_in: 'placed,approved,cancelled',
  reference_origin_not_null: 'true'
}

Filter with FilterHelper

import { Filter } from '@commercelayer/sdk-utils'

const filter: QueryFilter = {
  ...Filter.orders.number.eq('123'),
  ...Filter.orders.market.reference.eq('MKT'),
  ...Filter.orders.reference.or.customer.customer_group.reference.eq('REF'),
  ...Filter.orders.status.in('placed', 'approved', 'cancelled'),
  ...Filter.orders.reference_origin.not_null()
}

// The same as above but using a single instance of the orders helper
const of = Filter.orders

const filterSingle: QueryFilter = {
  ...of.number.eq('123'),
  ...of.market.reference.eq('MKT'),
  ...of.reference.or.customer.customer_group.reference.eq('REF'),
  ...of.status.in('placed', 'approved', 'cancelled'),
  ...of.reference_origin.not_null()
}

Filter using buildFilter function

import { buildFilter } from '@commercelayer/sdk-utils'

const filter: QueryFilter = buildFilter(
  of.number.eq('123'),
  of.market.reference.eq('MKT'),
  of.reference.or.customer.customer_group.reference.eq('REF'),
  of.status.in('placed', 'approved', 'cancelled'),
  of.reference_origin.not_null()
)