Storefront SDK

Build headless or embedded storefronts with the browser-safe Shoppex Storefront SDK

The Storefront SDK builds custom storefronts outside the Shoppex hosted theme runtime, for example a Next.js site, a plain HTML embed, or an app with its own checkout handoff.

Hosted Shoppex storefronts use ThemeDocuments, not this SDK. Start at Themes for hosted theme work.

Package names

Use @shoppexio/storefront in browser and headless storefront code. Use @shoppexio/sdk only on trusted servers that call the Developer API.

Simple example:

• Browser product grid: @shoppexio/storefront
• Backend order automation: @shoppexio/sdk
• Hosted Shoppex theme: ThemeDocument plus the platform commerce runtime

Do not ship a secret shx_... API key in browser code. @shoppexio/sdk is for trusted backend code only.

What the SDK does

Public catalog reads

Fetch store metadata, products, groups, reviews, and listing data from public storefront endpoints.

Browser cart state

Add, update, and remove cart items. Cart data stays saved locally in the browser.

Hosted checkout handoff

Create a checkout handoff and redirect customers to Shoppex hosted checkout.

Framework neutral

Works with React, Vue, Svelte, Astro, plain HTML, or any browser runtime.

Install the SDK

Use the CDN build for the fastest start, with one script tag and no build step. Use npm instead if you have a bundler and want TypeScript types.

<script src="https://cdn.shoppex.io/sdk/v1.0/shoppex.umd.js"></script>

For ESM imports without npm, load the module build directly.

<script type="module">
  import shoppex from 'https://cdn.shoppex.io/sdk/v1.0/shoppex.esm.js';

  shoppex.init('your-store');
</script>

Install the SDK as a dependency with npm, yarn, or pnpm.

npm

npm install @shoppexio/storefront

Then import and use the SDK.

import shoppex from '@shoppexio/storefront';

shoppex.init('your-store');

Initialize and run your first request

After you load the SDK, initialize it with your store slug.

shoppex.init('your-store', {
  locale: 'en',        // Optional: default language
  currency: 'USD',     // Optional: default currency
});

storeSlug · string · required

Your store’s unique identifier. Find this in your Shoppex dashboard under Settings.

options.locale · string · default: "en"

Default language for the SDK. Affects price formatting and checkout language.

options.currency · string

Override the store’s default currency. Must be a valid ISO 4217 currency code.

Initialize the SDK, fetch the store’s products, then add the first one to the cart.

shoppex.init('your-store');

const { data } = await shoppex.getStorefront();

data.products.forEach((product) => {
  console.log(product.title, product.price);
});

shoppex.addToCart(data.products[0].uniqid, '', 1);

This loads every product in the store and adds the first one to the cart with no variant selected. See the reference for other ways to fetch products and the full set of cart options.

A full flow, from catalog read to checkout, looks like this.

<script src="https://cdn.shoppex.io/sdk/v1.0/shoppex.umd.js"></script>
<script>
  shoppex.init('your-store');

  const response = await shoppex.getStorefront();
  const products = response.data.products;

  products.forEach((product) => {
    console.log(product.title, product.cdn_image_url);
  });

  shoppex.addToCart('product-id', 'variant-id', 1);
  await shoppex.checkout();
</script>

Check that the SDK loaded and initialized before you call other methods.

// Check if SDK is loaded
if (typeof shoppex !== 'undefined') {
  console.log('SDK loaded');
}

// Check if SDK is initialized
if (shoppex.isInitialized()) {
  console.log('SDK initialized for:', shoppex.getConfig().storeSlug);
}

TypeScript and browser support

The SDK includes TypeScript definitions. Import types directly.

import shoppex, {
  type Product,
  type CartItem,
  type ShoppexConfig
} from '@shoppexio/storefront';

The SDK supports all modern browsers.

Browser	Minimum version
Chrome	60+
Firefox	55+
Safari	12+
Edge	79+

Internet Explorer is not supported. The SDK uses modern JavaScript features such as Promises, async/await, and ES6+ syntax.

Use the Developer API for server work

The Storefront SDK is browser-safe and public. It does not replace the Developer API.

Use the Developer API from your server when you need to:

• create catalog-backed orders
• manage customers
• validate licenses
• fulfill orders
• manage webhooks
• read private operational data