@commercelayer/sdk
Advanced tools
A JavaScript Library wrapper that makes it quick and easy to interact with the Commerce Layer API.
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.
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.
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
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.
You can use the ES6 default import with the SDK like so:
import CommerceLayer from '@commercelayer/sdk'
const cl = CommerceLayer({
organization: 'your-organization-slug',
accessToken: 'your-access-token'
})
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.
// Select the shipping category (it's a required relationship for the SKU resource)
const shippingCategories = await cl.shipping_categories.list({ filters: { name_eq: 'Merchandising' } })
const attributes = {
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
}
const newSku = await cl.skus.create(attributes)
ℹ️ Check our API reference for more information on how to create an SKU.
// Fetch the SKU by ID
const sku = await cl.skus.retrieve('BxAkSVqKEn')
// Fetch all SKUs and filter by code
const sku = await cl.skus.list({ filters: { code_eq: 'TSHIRTMM000000FFFFFFXLXX' } })
// Fetch the first SKU of the list
const sku = (await cl.skus.list()).first()
// Fetch the last SKU of the list
const sku = (await cl.skus.list()).last()
ℹ️ Check our API reference for more information on how to retrieve an SKU.
// Fetch all the SKUs
const skus = await cl.skus.list()
When fetching a collection of resources you can leverage the meta attribute to get its meta information like so:
const skus = await cl.skus.list()
const meta = skus.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 skus = await cl.skus.list({ sort: { created_at: 'asc' } })
// Sort the results by creation date in descending order
const skus = 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 skus = await cl.skus.list({ include: [ 'prices' ] })
// Include an association (stock items)
const skus = 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 skus = await cl.skus.list({ fields: { skus: [ 'name', 'metadata' ] } })
// Request the API to return only specific fields of the included resource
const skus = 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 skus = await cl.skus.list({ filters: { code_start: 'TSHIRT' } })
// Filter all the SKUs fetching only the ones whose code ends with the string "XLXX"
const skus = await cl.skus.list({ filters: { code_end: 'XLXX' } })
// Filter all the SKUs fetching only the ones whose name contains the string "White Logo"
const skus = 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 skus = 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 skus = 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 skus = 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 skus = await cl.skus.list({ pageNumber: 3, pageSize: 5 })
// Get the total number of SKUs in the collection
const skuCount = skus.meta.recordCount
// Get the total number of pages
const pageCount = skus.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.
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 skus = await cl.skus.list()
skus.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 = cl.orders.billing_address('xYZkjABcde')
// Fetch 1-to-N related resources: orders associated to a customer
const orders = cl.customers.orders('XyzKjAbCDe', { fields: ['status', 'number'] })
In general:
/api/customers or /api/customers/<customerId> translates to cl.customers or cl.customers('<customerId>') with the SDK./api/orders/<orderId>/shipping_address translates to cl.orders('<orderId>', { include: ['shipping_address'] }} with the SDK./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 = cl.orders.count({ filters: { status_eq: 'placed' } })
const sku = {
id: 'xYZkjABcde',
description: 'Updated description...',
imageUrl: '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.
cl.skus.delete('xYZkjABcde') // persisted deletion
ℹ️ Check our API reference for more information on how to delete an SKU.
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 skus = await cl.skus.list()
or
// Use configuration at request level
cl.skus.list({}, { organization: 'you-organization-slug', accessToken: 'your-access-token' })
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.
Fork this repository (learn how to do this here).
Clone the forked repository like so:
git clone https://github.com/<your username>/commercelayer-sdk.git && cd commercelayer-sdk
Make your changes and create a pull request (learn how to do this).
Someone will attend to your pull request and provide some feedback.
Create an issue in this repository.
Ping us on Twitter.
This repository is published under the MIT license.
FAQs
Commerce Layer Javascript SDK
The npm package @commercelayer/sdk receives a total of 3,460 weekly downloads. As such, @commercelayer/sdk popularity was classified as popular.
We found that @commercelayer/sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.