> ## 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: default language
  currency: 'USD',     // Optional: default currency
});
```

<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">
  Override the store's default currency. Must be a valid ISO 4217 currency code.
</ParamField>

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