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 @shoppexio/storefront 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/v1/shoppex.min.js"></script>

​
SDK Init

// @validate
import shoppex from '@shoppexio/storefront';

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

​
Fetch Storefront Data (Store + Products + Groups)

// @validate
import shoppex from '@shoppexio/storefront';

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, items } = res.data;
console.log(shop.name, products.length, groups.length, items.length);

​
Product Image URLs

Storefront product payloads now expose two primary image fields for different UI surfaces:
  • cdn_image_url for cards, listings, search results, cart rows, and other compact UI
  • detail_image_url for product detail pages, galleries, and zoom
Simple example:
  • product grid card -> product.cdn_image_url
  • PDP hero image -> product.detail_image_url
  • gallery strip -> product.images
If your custom storefront already renders the PDP hero from cdn_image_url, you should switch that hero to detail_image_url. Otherwise the page will keep using the smaller listing image.
items is the mixed storefront list in the merchant’s manual layout order. If the dashboard layout is Group A → Product X → Group B, render items for your storefront view instead of concatenating groups and products yourself.

​
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 '@shoppexio/storefront';

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, including mixed items order for storefront rendering
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.