@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.

License

MIT