@commercebuild/platform-api
JavaScript / TypeScript client library for Commercebuild Platform Services. Works in Node.js (>=22) and modern browsers, with native Fetch API. TypeScript type definitions included.
Installation
npm / yarn / pnpm
npm install @commercebuild/platform-api
# or
yarn add @commercebuild/platform-api
# or
pnpm add @commercebuild/platform-api
CDN (plain HTML)
<script src="https://unpkg.com/@commercebuild/[email protected]/dist/platform-api.min.js"></script>
Or via jsDelivr:
<script src="https://cdn.jsdelivr.net/npm/@commercebuild/[email protected]/dist/platform-api.min.js"></script>
The library is exposed as a global variable CommercebuildPlatform.
Quick Start
Bundler-based projects (React, Vue, Next.js, Vite, etc.)
import {createApi} from '@commercebuild/platform-api';
const api = createApi({
rootUrl: 'https://platform.yourdomain.com',
storeId: 'your-store-id',
accessToken: 'your-access-token',
});
const customer = await api.customer().getUserSelf();
console.log(customer);
Plain HTML via CDN
<script src="https://unpkg.com/@commercebuild/[email protected]/dist/platform-api.min.js"></script>
<script>
const api = CommercebuildPlatform.createApi({
rootUrl: 'https://platform.yourdomain.com',
storeId: 'your-store-id',
accessToken: 'your-access-token',
});
api.customer().getUserSelf().then(console.log);
</script>
Inside a Commercebuild storefront page
<script src="https://unpkg.com/@commercebuild/[email protected]/dist/platform-api.min.js"></script>
<script>
const api = CommercebuildPlatform.createWebApiInStoreV4({
storeId: 'your-store-id',
uniqueId: 'myPlatformApi',
});
</script>
Authentication
The library supports several token strategies:
createApi({
rootUrl: 'https://platform.yourdomain.com',
storeId: 'your-store-id',
// Option 1: static token
accessToken: 'eyJhbGc...',
// Option 2: dynamic token (sync or async)
// accessToken: async () => fetchTokenFromSomewhere(),
// Option 3: auto-refresh on 401
// refreshAccessToken: async () => fetchNewToken(),
});
On 401 Unauthorized, if refreshAccessToken is provided, the library automatically retries the request with a fresh token and emits a TokenUpdatedByRefreshAccessToken event.
Available Services
api.cart() // shopping cart (v1, v2)
api.catalog() // product catalog
api.checkout() // checkout flow
api.customer() // customer profiles
api.files() // file storage
api.grid() // pricing grids
api.notification() // notifications
api.oauth() // OAuth tokens
api.order() // orders, quotes, shipments, transactions
api.payment() // payment processors
api.price() // pricing
api.promotion() // promotions / coupons
api.setting() // platform settings
api.shipping() // shipping methods
api.stock() // inventory
api.sync() // integration sync
Each service is versioned. Use api.cart('2') to pin to a specific version.
API Versions
const cartV1 = api.cart('1');
const cartV2 = api.cart('2');
const cart = api.cart(); // defaults to v1
Events
api.on('TokenUpdated', (token) => { /* refresh-token flow succeeded */ });
api.on('TokenInvalid', () => { /* both access + refresh expired */ });
TypeScript
Full type definitions are bundled. All request/response shapes are typed.