> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  Hosted Shoppex storefronts use ThemeDocuments, not this SDK. Start at [Themes](/storefront/themes) for hosted theme work.
</Note>

## 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

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

## What the SDK does

<CardGroup cols={2}>
  <Card title="Public catalog reads" icon="box">
    Fetch store metadata, products, groups, reviews, and listing data from public storefront endpoints.
  </Card>

  <Card title="Browser cart state" icon="cart-shopping">
    Add, update, and remove cart items. Cart data stays saved locally in the browser.
  </Card>

  <Card title="Hosted checkout handoff" icon="lock">
    Create a checkout handoff and redirect customers to Shoppex hosted checkout.
  </Card>

  <Card title="Framework neutral" icon="feather">
    Works with React, Vue, Svelte, Astro, plain HTML, or any browser runtime.
  </Card>
</CardGroup>

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

```html theme={"system"}
<script src="https://cdn.shoppex.io/sdk/v1.0/shoppex.umd.js"></script>
```

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

```html theme={"system"}
<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.

<CodeGroup>
  ```bash npm theme={"system"}
  npm install @shoppexio/storefront
  ```

  ```bash yarn theme={"system"}
  yarn add @shoppexio/storefront
  ```

  ```bash pnpm theme={"system"}
  pnpm add @shoppexio/storefront
  ```
</CodeGroup>

Then import and use the SDK.

```typescript theme={"system"}
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.

```javascript theme={"system"}
shoppex.init('your-store', {
  locale: 'en',        // Optional: catalog language
  currency: 'EUR',     // Optional: buyer currency, must be enabled in the shop
});
```

<ParamField path="storeSlug" type="string" required>
  Your store's unique identifier. Find this in your Shoppex dashboard under Settings.
</ParamField>

<ParamField path="options.locale" type="string" default="en">
  Default language for the SDK. Affects price formatting and checkout language.
</ParamField>

<ParamField path="options.currency" type="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.
</ParamField>

<Note>
  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.
</Note>

```javascript theme={"system"}
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.

```javascript theme={"system"}
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](/developers/storefront-sdk/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.

```html theme={"system"}
<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.

```javascript theme={"system"}
// 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.

```typescript theme={"system"}
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+             |

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

## 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