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 install @shoppexio/storefront

yarn add @shoppexio/storefront

pnpm add @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: catalog language
  currency: 'EUR',     // Optional: buyer currency, must be enabled in the shop
});

string

required

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

string

default:"en"

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

string

Buyer currency for every priced read (getStorefront, getStore, getProducts, getProduct) and for cart quotes and checkout. ISO 4217 code, and it must be one of the currencies enabled in the shop’s settings. Omit it to let the shop default and its country auto-detection decide. A ?currency= parameter on the page URL takes precedence over this option, for catalog reads and checkout alike.

The currency is enforced, not a hint. A currency the shop has not enabled makes every priced read fail with the code errors.storefront.currency_unavailable, and errorParams.available lists the enabled currencies. The SDK never silently falls back to the shop default. Enable the currency under Settings → Currencies in the dashboard, or drop the option.

const { success, code, errorParams, data } = await shoppex.getStorefront();

if (!success && code === 'errors.storefront.currency_unavailable') {
  console.error(`Shop does not sell in ${errorParams.requested}; enabled: ${errorParams.available.join(', ')}`);
}

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

Start here

Invoices and payments

Webhooks

Headless commerce

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Storefront SDK

Package names

What the SDK does

Public catalog reads

Browser cart state

Hosted checkout handoff

Framework neutral

Install the SDK

Initialize and run your first request

TypeScript and browser support

Use the Developer API for server work

​Package names

​What the SDK does

Public catalog reads

Browser cart state

Hosted checkout handoff

Framework neutral

​Install the SDK

​Initialize and run your first request

​TypeScript and browser support

​Use the Developer API for server work

Package names

What the SDK does

Install the SDK

Initialize and run your first request

TypeScript and browser support

Use the Developer API for server work