@shoppexio/storefront

Official JavaScript storefront SDK for Shoppex.

Use this package when you want to embed Shoppex products, cart behavior, and hosted checkout into a custom frontend.

Good fit

Use this package for:

• product loading
• cart state
• checkout redirects
• storefront helpers

Install

npm install @shoppexio/storefront

Quick start

import shoppex from '@shoppexio/storefront';

shoppex.init('my-store');

const products = await shoppex.getProducts();
shoppex.addToCart(products.data?.[0]?.uniqid ?? '', 'default', 1, {
  custom_fields: {
    customer_note: 'Gift order',
  },
});
await shoppex.checkout();

Cart items use a stable line_id. Use this identifier for cart updates and removals because one product can have multiple cart configurations.

const [line] = shoppex.getCart();

if (line) {
  shoppex.updateCartItem(line.line_id, { quantity: 2 });
  shoppex.removeFromCart(line.line_id);
}

Buyer currency

shoppex.init('store-slug', { currency: 'EUR' }) prices every catalog read (getStorefront, getStore, getProducts, getProduct) in that currency and uses it for cart quotes and checkout. The currency must be enabled in the shop's settings: a read for a currency the shop does not sell in fails with code: 'errors.storefront.currency_unavailable' and errorParams.available listing the enabled ones. Nothing falls back to the shop default silently. data.shop.currency names the currency a response is priced in; default_currency and available_currencies describe the shop's setup.

Multi-currency checkout

When buyers can select a storefront currency, quote the cart and create the invoice with the same currency:

const selectedCurrency = 'EUR';
await shoppex.quoteCart(undefined, selectedCurrency);

const checkoutUrl = await shoppex.buildCheckoutUrl({
  currency: selectedCurrency,
});

After a currency change, quote the cart again before checkout. Quote tokens are currency-bound; Shoppex rejects a mismatch as errors.checkout.quote_token_stale instead of creating an invoice for a total the buyer did not approve.

Custom customer account

Build your own OTP login, order history, and download UI without adding a merchant API key or custom backend. Headless customer accounts are available on every Shoppex plan; only the separate Headless Checkout SDK requires Business:

import { createCustomerClient } from '@shoppexio/storefront/customer';

const customer = createCustomerClient({
  shop: 'my-store',
  publishableKey: 'pk_live_your_key',
});

await customer.requestOtp('[email protected]');
await customer.verifyOtp('[email protected]', '123456', { rememberMe: true });

const orders = await customer.orders();
const firstOrder = orders.invoices[0];

if (firstOrder) {
  const order = await customer.order(firstOrder.uniqid);

  for (const item of order.lineItems) {
    const instructions = item.deliveryText ?? item.product?.serviceText;
    console.log(item.deliveryStatus, instructions, item.deliverySummary);
  }
}

The publishable key comes from Settings -> Developer -> Headless; the current browser origin must be an allowed site in Store -> Embed Hub. rememberMe is opt-in and keeps the buyer signed in for up to 30 days.

The order detail includes delivery status, service instructions, codes, serials, notes, links, and file indexes. Delivery content appears only after Shoppex marks the item as delivered. Sanitize rich-text delivery instructions before you render them as HTML.

Coupon validation

Use the options form when validating a coupon for a selected product variant:

const result = await shoppex.validateCoupon('SAVE10', {
  productId: 'prod_abc123',
  variantId: 'variant_lifetime',
});

Calling validateCoupon(code) without options validates against the current SDK cart. Affiliate/referral codes are separate and should use validateAffiliateCode or applyAffiliateCode. If program_enabled is false in an affiliate validation response, the shop-level affiliate program is disabled even if individual links exist.

Live online users

The SDK can power a custom live online visitor counter. It provides the data; your storefront renders the badge.

import shoppex from '@shoppexio/storefront';

shoppex.init('my-store');

async function refreshLiveUsers() {
  await shoppex.touchStorefrontPresence();

  const result = await shoppex.getStorefrontOnlineUsers();
  if (result.success && result.data) {
    console.log(`${result.data.count} online`);
  }
}

await refreshLiveUsers();
setInterval(refreshLiveUsers, 30_000);

getShopReviewsPage(cursor, { product }) pages the shop's reviews on demand; pass a product's id to page only its reviews, with a summary for that product.

touchStorefrontPresence() keeps the visitor online but never counts as a page view, so it is safe on a timer. Report page views with trackPageView() (once per page load or navigation) and later cart changes with trackCartActivity(cartValue, itemCount), which updates the live visitor map without counting a view.

Not this package

If you want the authenticated Developer API wrapper for backend integrations, use @shoppexio/sdk. Do not ship @shoppexio/sdk in a browser bundle; use this Storefront SDK for headless storefronts.

Docs

• Storefront docs: docs.shoppex.io/sdk/introduction
• Installation: docs.shoppex.io/sdk/installation
• Headless customer accounts: docs.shoppex.io/developers/headless/customer-accounts