Shoppex Storefront SDK

Build custom storefronts with any framework using the Shoppex SDK.

Installation

CDN (Recommended for quick start)

<script src="https://cdn.shoppex.io/sdk/v0.3/shoppex.umd.js"></script>

Use the moving minor channel for managed updates. Simple example: v0.3 moves to the latest 0.3.x release.

If you need a locked production rollout, pin an exact version:

<script src="https://cdn.shoppex.io/sdk/<exact-version>/shoppex.umd.js"></script>

/sdk/latest/ stays available for internal and development usage only.

npm

npm install @shoppexio/storefront

Quick Start

<script src="https://cdn.shoppex.io/sdk/v0.3/shoppex.umd.js"></script>
<script>
  // Initialize with your store slug
  shoppex.init('my-store');

  // Get store info
  shoppex.getStore().then(function(result) {
    if (result.success) {
      console.log('Store:', result.data.name);
    }
  });

  // Add product to cart
  shoppex.addToCart('product-id', 'variant-id', 2);

  // Checkout (redirects to hosted checkout)
  document.getElementById('checkout-btn').onclick = function() {
    shoppex.checkout();
  };
</script>

ES Modules (with async/await)

<script type="module">
  import shoppex from 'https://cdn.shoppex.io/sdk/v0.3/shoppex.esm.js';

  shoppex.init('my-store');

  const store = await shoppex.getStore();
  const products = await shoppex.getProducts();

  shoppex.addToCart(products.data[0].uniqid, 'default', 1);

  await shoppex.checkout();
</script>

API Reference

Initialization

// Simple init
shoppex.init('store-slug');

// With options
shoppex.init({
  storeId: 'store-slug',
  locale: 'de',
  currency: 'EUR'
});

Store

const store = await shoppex.getStore();
// → { success: true, data: { id, name, currency, ... } }

const logoUrl = await shoppex.getStoreLogoUrl();
const bannerUrl = await shoppex.getStoreBannerUrl();

Products

const products = await shoppex.getProducts();
// → { success: true, data: [{ uniqid, title, price, images[], variants[], addons[], faqs[], feedback, ... }] }
//    variants[] mirrors price_variants[] (legacy field); both are present for compatibility.
//    images[] contains the full product gallery; the first entry is the primary image.

const product = await shoppex.getProduct('product-id-or-slug');
const categories = await shoppex.getCategories();

Cart

// Simple add
shoppex.addToCart('productId', 'variantId', 2);

// With Shoppex features (addons, custom fields)
shoppex.addToCart('productId', 'variantId', 1, {
  addons: [
    { id: 'addon_gift_wrap', quantity: 1 }
  ],
  customFields: {
    'engraving_text': 'Happy Birthday!'
  },
  priceVariantId: 'price_premium'
});

// Get cart
const cart = shoppex.getCart();
const itemCount = shoppex.getCartItemCount();

// Manage cart
shoppex.removeFromCart('productId', 'variantId');
shoppex.clearCart();

// Backup/restore (useful for error recovery)
shoppex.createCartBackup();
shoppex.restoreCartFromBackup();

Checkout

// Simple checkout (auto-redirects)
await shoppex.checkout();

// With coupon
await shoppex.checkout('SAVE20');

// Get URL without redirecting
const result = await shoppex.checkout('SAVE20', { autoRedirect: false });
console.log(result.redirectUrl);

Coupons

const result = await shoppex.validateCoupon('SAVE20', {
  productId: 'product-id',
  variantId: 'variant-id',
});
// -> { success: true, data: { valid: true, discount: 20, restriction_scope: 'variants' } }

Affiliate Codes

Affiliate/referral codes are separate from coupon codes. Validate and store them before checkout:

const affiliate = await shoppex.applyAffiliateCode('creator10');

if (affiliate.data?.program_enabled === false) {
  throw new Error('Affiliate program is disabled for this shop');
}

await shoppex.checkout({
  coupon: 'SAVE20',
  affiliateCode: affiliate.data?.affiliate_code,
});

Reviews

const reviews = await shoppex.getShopReviews();
// → { success: true, data: [{ rating, comment, ... }] }

Invoices

const invoice = await shoppex.getInvoice('invoice-id');
const status = await shoppex.getInvoiceStatus('invoice-id');

Formatting

const formatter = shoppex.createFormatter('USD', 'en-US');
formatter.format(29.99); // → "$29.99"

// Or directly
shoppex.formatPrice(29.99, 'EUR', 'de-DE'); // → "29,99 €"

Shoppex Features

The SDK supports Shoppex-specific features not found in competitors:

| Feature | Description | |---------|-------------| | Product Addons | Express shipping, gift wrap, etc. | | Custom Fields | Customer input (engraving, gift message) | | Price Variants | Different pricing tiers | | Multiple Gateways | Stripe, PayPal, Crypto |

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

TypeScript

Full TypeScript support with type definitions included.

import shoppex, { Product, CartItem } from '@shoppexio/storefront';

const products: Product[] = (await shoppex.getProducts()).data ?? [];

License

MIT