Skip to main content

​
Runtime And SDK

Themes use the Shoppex SDK to load storefront data and drive cart + checkout behavior. There are two common ways to use the SDK in a theme:
  • CDN (global): load the SDK with a <script> tag, then use window.shoppex
  • npm: install @shoppex/sdk and import it
Our reference themes load the SDK via CDN.
Even if your theme runs on localhost, you can still fetch data from the public API by setting VITE_API_BASE_URL=https://api.shoppex.io.

​
CDN vs npm

<!-- In index.html -->
<script src="https://cdn.shoppex.io/sdk/latest/shoppex.umd.js"></script>

​
SDK Init

// @validate
import shoppex from '@shoppex/sdk';

shoppex.init('my-shop', {
  apiBaseUrl: 'https://api.shoppex.io',
});

​
Fetch Storefront Data (Store + Products + Groups)

// @validate
import shoppex from '@shoppex/sdk';

shoppex.init('my-shop', { apiBaseUrl: 'https://api.shoppex.io' });

const res = await shoppex.getStorefront();
if (!res.success || !res.data) {
  throw new Error(res.message ?? 'Failed to load storefront');
}

const { shop, products, groups } = res.data;
console.log(shop.name, products.length, groups.length);

​
Resolve Shop By Domain (Custom Domains)

If your theme is running on a custom domain, you can resolve the shop first: 
// @validate
import shoppex from '@shoppex/sdk';

const apiBaseUrl = 'https://api.shoppex.io';
const domain = 'example.com';

const resolved = await shoppex.resolveStoreByDomain(domain, apiBaseUrl);
if (resolved.success && resolved.data) {
  const slug = resolved.data.slug ?? resolved.data.name;
  shoppex.init(slug, { apiBaseUrl });
}

​
Source

Reference implementation:
  • themes/default/src/main.tsx
  • themes/default/src/hooks/useStore.ts

​
getStore() vs getStorefront()

MethodReturnsUse When
getStore()SDKResponse<Shop>You only need store metadata (name, logo, settings)
getStorefront()SDKResponse<StorefrontData>You need store + products + groups in one call (most common)
getStorefront() is the recommended method for initial page load — it fetches everything in a single API call.

​
Next Steps

Cart & Checkout

Add to cart, coupons, and checkout flow.

SDK Reference

Complete API reference for all SDK methods.

Theme Settings

Load published settings and apply them (typically via CSS variables).

Troubleshooting

If data does not load, start here.