Storefront SDK reference

This page lists every method and type in @shoppexio/storefront, grouped by object: Store, Products, Cart, Checkout, Reviews and invoices, and Types.

All async SDK methods return SDKResponse<T>, a wrapper containing data, error, and status fields. See Response types for the full definition.

Store

The Store object gives access to your shop’s public information, including name, branding, and settings.

For simple cases such as displaying the store logo, use getStoreLogoUrl() or getStoreBannerUrl(). They are lightweight wrappers that avoid fetching the full store metadata.

getStore

Fetches the store’s public metadata.

const { data: store } = await shoppex.getStore();

console.log(store.name);     // "My Awesome Store"
console.log(store.currency); // "USD"

Response

Shop

Show Shop object

string

Unique store identifier

string

Store display name

string

URL-friendly store identifier

string

Custom domain if configured

string

Store description

string

Default currency (ISO 4217)

string

Logo image URL

string

Banner image URL

number

Average store rating (1-5)

boolean

Whether terms of service are enabled

Social media links

Show child attributes

string

Discord URL

string

Twitter URL

string

Instagram URL

string

Facebook URL

string

Telegram URL

string

YouTube URL

string

Reddit URL

string

TikTok URL

Example: display store header

async function renderStoreHeader() {
  const { data: store } = await shoppex.getStore();

  document.getElementById('store-header').innerHTML = `
    <img src="${store.logo}" alt="${store.name}" class="logo" style="border-radius: 9999px;">
    <h1>${store.name}</h1>
    ${store.rating ? `<span class="rating">${store.rating.toFixed(1)} / 5</span>` : ''}
  `;
}

getStoreLogoUrl

Returns the store’s logo URL directly.

const logoUrl = await shoppex.getStoreLogoUrl();

if (logoUrl) {
  document.getElementById('logo').src = logoUrl;
}

Response

string | null

Logo URL or null if no logo is set

getStoreBannerUrl

Returns the store’s banner URL directly.

const bannerUrl = await shoppex.getStoreBannerUrl();

if (bannerUrl) {
  document.getElementById('hero').style.backgroundImage = `url(${bannerUrl})`;
}

Response

string | null

Banner URL or null if no banner is set

Store error handling

try {
  const { data, success, message } = await shoppex.getStore();

  if (!success) {
    console.error('Failed to load store:', message);
    return;
  }

  // Use store data
} catch (error) {
  if (error.name === 'NotInitializedError') {
    console.error('SDK not initialized. Call shoppex.init() first.');
  } else if (error.name === 'NetworkError') {
    console.error('Network error. Check your connection.');
  }
}

Products

Fetch products from your store, including variants, addons, and custom fields.

getProducts

Fetches all products from the store.

const { data: products } = await shoppex.getProducts();

products.forEach(product => {
  console.log(product.title, product.price);
});

Response

Product[]

Array of products

Show Product object

string

Unique product identifier

string

Product name

string

Base price as string (for precision). Use shoppex.formatPrice() to display.

string

Currency code (ISO 4217)

string

URL-friendly product identifier

string

Full product description (HTML)

{ title: string; content: string }[]

Merchant-defined extra description tabs (for example, Features, Specifications). content is HTML. Empty array when the product has no extra tabs.

ProductImage[]

Array of product images

string | null

Optimized cover image for cards, listings, search results, and other non-zoomed UI.

string | null

High-resolution primary image for product detail pages, galleries, and zoom views.

string | null

Optional product video URL (YouTube, Streamable, or Vimeo). null when no video is configured.

ProductVariant[]

Available variants (for example, size, color)

ProductAddon[]

Optional add-ons

PriceVariant[]

Price-based variants (for example, subscription tiers)

CustomFieldDefinition[]

Custom input fields for checkout

number

Available stock quantity

ProductCategory[]

Product categories as objects with uniqid and title

Product prices are returned as string types to preserve decimal precision. Always use shoppex.formatPrice() for display. Do not calculate directly with price strings.

Use product images by surface:

cdn_image_url for product cards, category grids, cart rows, and search results
detail_image_url for product detail pages, image galleries, and zoom
images[] for the full gallery

Simple example: if your custom storefront currently renders the PDP hero from cdn_image_url, switch that hero to detail_image_url to get the higher-resolution image.

Example: product grid

async function renderProducts() {
  const { data: products } = await shoppex.getProducts();
  const container = document.getElementById('products');

  container.innerHTML = products.map(product => `
    <div class="product-card">
      <img src="${product.cdn_image_url || product.images[0]?.url || ''}" alt="${product.title}" style="border-radius: 8px;">
      <h3>${product.title}</h3>
      <span class="price">
        ${shoppex.formatPrice(product.price, product.currency)}
      </span>
      ${product.stock < 10 ? '<span class="low-stock">Only ' + product.stock + ' left!</span>' : ''}
    </div>
  `).join('');
}

getProduct

Fetches a single product by ID or slug.

const { data: product } = await shoppex.getProduct('prod_abc123');

console.log(product.title);
console.log(product.variants);

Parameters

string

required

Product unique ID or URL slug

Example: product detail page

async function renderProductDetail(productId) {
  const { data: product } = await shoppex.getProduct(productId);
  const galleryImages = product.images?.length
    ? product.images
    : [{ url: product.detail_image_url || product.cdn_image_url, alt: product.title }].filter(img => img.url);

  document.getElementById('product-detail').innerHTML = `
    <div class="gallery">
      ${galleryImages.map(img => `<img src="${img.url}" alt="${img.alt || product.title}" style="border-radius: 8px;">`).join('')}
    </div>
    <div class="info">
      <h1>${product.title}</h1>
      <p class="price">${shoppex.formatPrice(product.price, product.currency)}</p>
      <div class="description">${product.description}</div>

      ${product.variants?.length ? `
        <select id="variant-select">
          ${product.variants.map(v => `
            <option value="${v.id}">${v.title}</option>
          `).join('')}
        </select>
      ` : ''}

      ${product.video_link ? `
        <div class="product-video">
          <iframe src="${product.video_link}" title="${product.title}" allowfullscreen></iframe>
        </div>
      ` : ''}

      <button onclick="addToCart('${product.uniqid}')">Add to Cart</button>
    </div>
  `;
}

getCategories

Fetches all unique product category IDs from your store.

const { data: categories } = await shoppex.getCategories();

// Returns array of category uniqids (strings)
// ["cat_abc123", "cat_def456", "cat_ghi789"]

Example: category filter

async function renderCategoryFilter() {
  const { data: categories } = await shoppex.getCategories();

  document.getElementById('category-filter').innerHTML = `
    <select onchange="filterByCategory(this.value)">
      <option value="">All Categories</option>
      ${categories.map(cat => `
        <option value="${cat}">${cat}</option>
      `).join('')}
    </select>
  `;
}

async function filterByCategory(category) {
  const { data: products } = await shoppex.getProducts();

  const filtered = category
    ? products.filter(p => p.categories?.includes(category))
    : products;

  renderProducts(filtered);
}

Product groups

Stores can organize products into groups (for example, “Server Boosts”, “Tokens”). Groups come from getStorefront().

const { data: storefront } = await shoppex.getStorefront();

storefront.groups.forEach(group => {
  console.log(group.title, group.products_count);
});

Breaking change in @shoppexio/storefront 1.0.0 (and the underlying storefront API): groups no longer embed full product objects in products_bound. Each group now carries product_uniqids, an array of product references, and every public product, standalone and group-bound, appears exactly once in the flat products list. If your integration reads group.products_bound, it sees undefined and must migrate to the lookup pattern below.

Group object

string

Unique group identifier

string

Group name

string[]

References to the group’s products. Resolve them against the flat products list. The full product objects are not embedded in the group.

number

Number of products in the group

number

Display order of the group

Resolving group products Build a lookup from the flat products list and resolve each group’s references.

const { data: storefront } = await shoppex.getStorefront();

const byUniqid = new Map(storefront.products.map(p => [p.uniqid, p]));

storefront.groups.forEach(group => {
  const groupProducts = (group.product_uniqids ?? [])
    .map(uniqid => byUniqid.get(uniqid))
    .filter(Boolean);

  console.log(group.title, groupProducts.map(p => p.title));
});

If you install the SDK from npm, the same resolution is available as a named import.

import { getStorefrontGroupProducts } from '@shoppexio/storefront';

const groupProducts = getStorefrontGroupProducts(group, storefront.products);

Migrating from 0.3.x? Replace every group.products_bound read with the lookup above. getProducts() now returns the complete flat catalog, group-bound products included, so you no longer need to merge group products into your listing yourself. If you call the REST API directly, /v1/storefront/products/public/:slug groups carry product_uniqids. The /v1/storefront/products/shop/:name endpoint no longer returns groups at all. Read groups from the public catalog or bootstrap payload instead.

Working with variants

Products can have multiple variant types. Standard variants Variants such as size or color that do not change the price.

const product = await shoppex.getProduct('prod_abc');

product.variants.forEach(variant => {
  console.log(variant.id, variant.title);
  // "var_1", "Small"
  // "var_2", "Medium"
  // "var_3", "Large"
});

Price variants Variants that have different prices.

product.price_variants.forEach(pv => {
  console.log(pv.id, pv.label, pv.price);
  // "pv_1", "Basic", 9.99
  // "pv_2", "Pro", 29.99
  // "pv_3", "Enterprise", 99.99
});

Addons Optional extras the customer can add.

product.addons.forEach(addon => {
  console.log(addon.id, addon.name, addon.price, addon.required);
  // "addon_1", "Priority Support", 5.00, false
  // "addon_2", "Extended Warranty", 10.00, false
});

Products error handling

const { data, success, message } = await shoppex.getProduct('invalid-id');

if (!success) {
  console.error('Product not found:', message);
  // Show 404 page or redirect
}

Cart

The Cart object manages shopping cart state in the browser’s localStorage. Cart data stays saved across page refreshes and browser sessions.

Cart data is stored in the browser’s localStorage. If the user clears browser storage, the cart is lost.

getCart

Returns all items currently in the cart.

const cartItems = shoppex.getCart();

cartItems.forEach(item => {
  console.log(item.product_id, item.quantity);
});

Response

CartItem[]

Show CartItem object

string

Product unique identifier

string

Selected variant ID (empty string if no variant)

number

Item quantity

CartAddon[]

Selected add-ons

Record<string, string>

Custom field values

string

Selected price variant ID

getCartItemCount

Returns the total number of items in the cart.

const count = shoppex.getCartItemCount();
document.getElementById('cart-badge').textContent = count;

addToCart

Adds an item to the cart, or increments quantity if it already exists.

// Basic usage
shoppex.addToCart('prod_abc123', 'var_001', 1);

// With options
shoppex.addToCart('prod_abc123', 'var_001', 2, {
  addons: [{ id: 'addon_1', quantity: 1 }],
  custom_fields: { 'License Name': 'John Doe' },
  price_variant_id: 'pv_pro'
});

Parameters

string

required

Product unique identifier

string

required

Variant ID. Use empty string '' for products without variants.

number

default:"1"

Number of items to add

CartAddOptions

Show CartAddOptions

CartAddon[]

Add-ons to include

Record<string, string>

Custom field values

string

Selected price variant

Example: add to cart button

function handleAddToCart(productId, variantId) {
  const quantity = parseInt(document.getElementById('quantity').value) || 1;

  // Collect selected addons
  const addons = [];
  document.querySelectorAll('.addon-checkbox:checked').forEach(cb => {
    addons.push({ id: cb.value, quantity: 1 });
  });

  shoppex.addToCart(productId, variantId, quantity, { addons });

  // Update UI
  updateCartBadge();
  showNotification('Added to cart!');
}

updateCartItem

Updates an existing cart item.

shoppex.updateCartItem('prod_abc123', 'var_001', {
  quantity: 5,
  addons: [{ id: 'addon_2', quantity: 1 }]
});

Parameters

string

required

Product unique identifier

string

required

Variant ID

object

required

Show Update fields

number

New quantity

CartAddon[]

Updated add-ons

Record<string, string>

Updated custom fields

removeFromCart

Removes an item from the cart.

shoppex.removeFromCart('prod_abc123', 'var_001');

Parameters

string

required

Product unique identifier

string

required

Variant ID

clearCart

Removes all items from the cart.

shoppex.clearCart();

Cart backup

The SDK can back up the cart before checkout, to restore it if checkout is cancelled. createCartBackup

// Called automatically before checkout
shoppex.createCartBackup();

restoreCartFromBackup

// Restore cart after cancelled checkout
const restored = shoppex.restoreCartFromBackup();

if (restored) {
  console.log('Cart restored');
} else {
  console.log('No backup available');
}

Complete cart UI example

<div id="cart">
  <h2>Shopping Cart</h2>
  <div id="cart-items"></div>
  <div id="cart-total"></div>
  <button onclick="goToCheckout()">Checkout</button>
</div>

<script>
async function renderCart() {
  const items = shoppex.getCart();
  const container = document.getElementById('cart-items');

  if (items.length === 0) {
    container.innerHTML = '<p>Your cart is empty</p>';
    return;
  }

  // Fetch product details for display
  const { data: products } = await shoppex.getProducts();
  const productMap = new Map(products.map(p => [p.uniqid, p]));

  let total = 0;

  container.innerHTML = items.map(item => {
    const product = productMap.get(item.product_id);
    if (!product) return '';

    const itemTotal = product.price * item.quantity;
    total += itemTotal;

    return `
      <div class="cart-item">
        <img src="${product.images[0]?.url}" alt="${product.title}" style="border-radius: 8px;">
        <div class="item-info">
          <h4>${product.title}</h4>
          <p>${shoppex.formatPrice(product.price, product.currency)}</p>
        </div>
        <div class="quantity">
          <button onclick="updateQuantity('${item.product_id}', '${item.variant_id}', ${item.quantity - 1})">-</button>
          <span>${item.quantity}</span>
          <button onclick="updateQuantity('${item.product_id}', '${item.variant_id}', ${item.quantity + 1})">+</button>
        </div>
        <button onclick="removeItem('${item.product_id}', '${item.variant_id}')" class="remove">Remove</button>
      </div>
    `;
  }).join('');

  document.getElementById('cart-total').innerHTML = `
    <strong>Total: ${shoppex.formatPrice(total, products[0]?.currency || 'USD')}</strong>
  `;
}

function updateQuantity(productId, variantId, newQuantity) {
  if (newQuantity < 1) {
    shoppex.removeFromCart(productId, variantId);
  } else {
    shoppex.updateCartItem(productId, variantId, { quantity: newQuantity });
  }
  renderCart();
}

function removeItem(productId, variantId) {
  shoppex.removeFromCart(productId, variantId);
  renderCart();
}

renderCart();
</script>

Checkout

The Checkout object redirects customers to Shoppex hosted checkout. Checkout is fully hosted by Shoppex for PCI compliance.

checkout

Redirects the customer to the checkout page with their cart contents.

await shoppex.checkout();

Parameters

string

Pre-applied coupon code

CheckoutOptions

Show CheckoutOptions

boolean

default:"true"

Automatically redirect to checkout page

string

Override checkout language

Example: checkout with coupon

const couponCode = document.getElementById('coupon-input').value;

if (couponCode) {
  // Validate coupon first
  const { data } = await shoppex.validateCoupon(couponCode);

  if (!data.valid) {
    alert('Invalid coupon code');
    return;
  }
}

// Proceed to checkout
await shoppex.checkout(couponCode);

buildCheckoutUrl

Builds the checkout URL without redirecting. Use this to open checkout in a new tab or iframe.

const checkoutUrl = await shoppex.buildCheckoutUrl('SAVE10', { locale: 'de' });
console.log(checkoutUrl);
// https://yourstore.shoppex.io/checkout?coupon=SAVE10&locale=de&cart=...

Parameters

string

Coupon code to pre-apply

string

Checkout language (for example, ‘en’, ‘de’, ‘fr’)

Example: open checkout in new tab

async function openCheckoutInNewTab() {
  const url = await shoppex.buildCheckoutUrl();
  window.open(url, '_blank');
}

buildCheckoutUrlSync (deprecated)

buildCheckoutUrlSync is deprecated and throws immediately. Use buildCheckoutUrl() instead. It handles both default and custom domains.

Coupons

validateCoupon Validates a coupon code before checkout. Affiliate and referral codes are separate from coupons. Use validateAffiliateCode or applyAffiliateCode for those instead.

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

if (data.valid) {
  console.log('Discount:', data.discount, data.discount_type);
  // 10, "percentage" → 10% off
  // 5.00, "fixed" → $5 off
} else {
  console.log('Invalid or expired coupon');
}

Parameters

string

required

Coupon code to validate

string

Product ID to check product-specific coupons

string

Selected variant ID to check variant-specific coupons. Requires options.productId.

Response

CouponValidation

Show CouponValidation

boolean

Whether the coupon is valid

number

Discount amount

string

Either “percentage” or “fixed”

boolean

Whether the coupon is restricted to selected products

boolean

Whether the coupon is restricted to selected variants

string

One of “all”, “products”, “variants”, or “products_and_variants”

string[]

Public product IDs the coupon can apply to

string[]

Variant IDs the coupon can apply to

Affiliate codes

validateAffiliateCode Validates an affiliate or referral code without storing it.

const result = await shoppex.validateAffiliateCode('creator10');

if (result.success && result.data.valid) {
  console.log(result.data.affiliate_code);
} else if (result.data?.program_enabled === false) {
  console.log('Affiliate program is disabled for this shop');
}

applyAffiliateCode Validates and stores the normalized affiliate code. checkout() sends the stored code as affiliate_code.

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

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

Example: coupon input with validation

<div class="coupon-form">
  <input type="text" id="coupon-input" placeholder="Enter coupon code">
  <button onclick="applyCoupon()">Apply</button>
  <span id="coupon-status"></span>
</div>

<script>
let appliedCoupon = null;

async function applyCoupon() {
  const code = document.getElementById('coupon-input').value.trim();
  const status = document.getElementById('coupon-status');

  if (!code) {
    status.textContent = '';
    return;
  }

  const { data } = await shoppex.validateCoupon(code);

  if (data.valid) {
    appliedCoupon = code;
    if (data.discount_type === 'percentage') {
      status.textContent = `${data.discount}% off applied!`;
    } else {
      status.textContent = `$${data.discount} off applied!`;
    }
    status.className = 'success';
  } else {
    appliedCoupon = null;
    status.textContent = 'Invalid coupon';
    status.className = 'error';
  }
}

async function goToCheckout() {
  await shoppex.checkout(appliedCoupon);
}
</script>

Checkout flow

┌─────────────────────────────────────────────────────────────────┐
│                        Your Website                             │
├─────────────────────────────────────────────────────────────────┤
│  1. Customer browses products                                   │
│  2. Adds items to cart (SDK stores in localStorage)            │
│  3. Clicks "Checkout"                                          │
│  4. SDK calls shoppex.checkout()                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Shoppex Checkout                            │
│                   (yourstore.shoppex.io)                        │
├─────────────────────────────────────────────────────────────────┤
│  5. Customer enters email, billing info                        │
│  6. Selects payment method (Stripe, PayPal, Crypto)           │
│  7. Completes payment                                          │
│  8. Receives confirmation + delivery                           │
└─────────────────────────────────────────────────────────────────┘

After checkout

After successful checkout, the cart is automatically cleared. If you need to handle the return, read the order ID from the URL.

// Check URL for order confirmation
const urlParams = new URLSearchParams(window.location.search);
const orderId = urlParams.get('order');

if (orderId) {
  // Customer returned from successful checkout
  showOrderConfirmation(orderId);
}

Reviews and invoices

This section documents two separate objects: shop reviews and invoice status.

getShopReviews

Fetches all public reviews for the store.

const { data: reviews } = await shoppex.getShopReviews();

reviews.forEach(review => {
  console.log(review.rating, review.comment);
});

Response

Feedback[]

Show Feedback object

string

Review unique identifier

number

Star rating (1-5)

string

Review text

string

ISO timestamp

Example: reviews section

async function renderReviews() {
  const { data: reviews } = await shoppex.getShopReviews();
  const container = document.getElementById('reviews');

  // Calculate average
  const avgRating = reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length;

  container.innerHTML = `
    <div class="reviews-header">
      <h2>Customer Reviews</h2>
      <div class="average">
        ${'★'.repeat(Math.round(avgRating))}${'☆'.repeat(5 - Math.round(avgRating))}
        <span>${avgRating.toFixed(1)} / 5</span>
        <span>(${reviews.length} reviews)</span>
      </div>
    </div>

    <div class="reviews-list">
      ${reviews.map(review => `
        <div class="review">
          <div class="stars">${'★'.repeat(review.rating)}${'☆'.repeat(5 - review.rating)}</div>
          <p class="comment">${review.comment || ''}</p>
          <span class="date">${new Date(review.created_at).toLocaleDateString()}</span>
        </div>
      `).join('')}
    </div>
  `;
}

getInvoice

Fetches full invoice details.

const { data: invoice } = await shoppex.getInvoice('inv_abc123');

console.log(invoice.status);   // "COMPLETED"
console.log(invoice.total);    // 29.99
console.log(invoice.products); // [{ title, quantity, price }]

Response

Invoice

Show Invoice object

string

Invoice unique identifier

string

Invoice status (PENDING, COMPLETED, CANCELLED, and more)

number

Total amount

string

Currency code

InvoiceProduct[]

Purchased products

getInvoiceStatus

Lightweight endpoint for status polling. Use this instead of getInvoice for real-time updates.

const { data } = await shoppex.getInvoiceStatus('inv_abc123');
console.log(data.status); // "PENDING" | "COMPLETED" | "CANCELLED"

Example: order status page

async function pollOrderStatus(invoiceId) {
  const statusEl = document.getElementById('order-status');

  const checkStatus = async () => {
    const { data } = await shoppex.getInvoiceStatus(invoiceId);

    switch (data.status) {
      case 'PENDING':
        statusEl.innerHTML = '<span class="pending">Waiting for payment...</span>';
        break;
      case 'PROCESSING':
        statusEl.innerHTML = '<span class="processing">Processing payment...</span>';
        break;
      case 'COMPLETED':
        statusEl.innerHTML = '<span class="success">Order complete! Check your email.</span>';
        clearInterval(pollInterval);
        break;
      case 'CANCELLED':
        statusEl.innerHTML = '<span class="error">Order cancelled</span>';
        clearInterval(pollInterval);
        break;
    }
  };

  // Poll every 5 seconds
  const pollInterval = setInterval(checkStatus, 5000);
  checkStatus(); // Initial check
}

// Get invoice ID from URL
const invoiceId = new URLSearchParams(window.location.search).get('invoice');
if (invoiceId) {
  pollOrderStatus(invoiceId);
}

Formatting utilities

formatPrice Formats a price with a currency symbol.

shoppex.formatPrice(29.99, 'USD');       // "$29.99"
shoppex.formatPrice(29.99, 'EUR');       // "€29.99"
shoppex.formatPrice(29.99, 'EUR', 'de'); // "29,99 €"

Parameters

number

required

Price amount

string

default:"Store currency"

ISO 4217 currency code

string

default:"en"

Locale for formatting

createFormatter Creates a reusable Intl.NumberFormat instance.

const formatter = shoppex.createFormatter('EUR', 'de');

formatter.format(29.99);  // "29,99 €"
formatter.format(100);    // "100,00 €"

Types

The SDK is written in TypeScript and exports all type definitions. Install with npm to get full IntelliSense support.

Configuration types

interface ShoppexConfig {
  storeSlug: string;
  locale?: string;
  currency?: string;
  apiBaseUrl?: string;
}

interface ShoppexInitOptions {
  locale?: string;
  currency?: string;
  apiBaseUrl?: string;
}

Response types

interface SDKResponse<T> {
  success: boolean;
  data?: T;
  message?: string;
}

Store types

interface Shop {
  id: string;
  name: string;
  slug: string;
  domain?: string;
  description?: string;
  currency: string;
  logo?: string;
  banner?: string;
  rating?: number;
  tos_enabled?: boolean;
}

Product types

interface ProductCategory {
  uniqid: string;
  title: string;
}

interface Product {
  uniqid: string;
  title: string;
  slug?: string;
  description?: string;
  price: string;           // String for precision
  price_display?: string;  // Formatted display price
  currency: string;
  stock?: number;
  cdn_image_url?: string | null;    // Card/listing/search image
  detail_image_url?: string | null; // PDP/gallery/zoom image
  images: ProductImage[];
  variants?: ProductVariant[];
  addons?: ProductAddon[];
  price_variants?: PriceVariant[];
  custom_fields?: string | unknown[] | null;
  categories?: ProductCategory[];
}

interface ProductImage {
  id: string;
  url: string;
  cloudflare_image_id?: string;
  alt?: string;
}

interface ProductVariant {
  id: string;
  title: string;
  price?: number;
  stock?: number;
}

interface ProductAddon {
  id: string;
  name: string;
  price: number;
  required?: boolean;
}

interface PriceVariant {
  id: string;
  label: string;
  price: number;
}

interface CustomFieldDefinition {
  id: string;
  name: string;
  type: 'text' | 'textarea' | 'select' | 'checkbox';
  required?: boolean;
  options?: string[];
}

Image fields have different jobs:

cdn_image_url is the optimized storefront cover for cards and lists
detail_image_url is the higher-resolution primary image for product detail pages
images[] contains the gallery

If you run a headless storefront, keep cards on cdn_image_url and switch your PDP hero and gallery to detail_image_url.

Cart types

interface CartItem {
  product_id: string;
  variant_id: string;
  quantity: number;
  addons?: CartAddon[];
  custom_fields?: Record<string, string>;
  price_variant_id?: string;
}

interface CartAddon {
  id: string;
  quantity?: number;
}

interface CartAddOptions {
  addons?: CartAddon[];
  custom_fields?: Record<string, string>;
  price_variant_id?: string;
}

interface CartUpdateOptions {
  quantity?: number;
  addons?: CartAddon[];
  custom_fields?: Record<string, string>;
  price_variant_id?: string;
}

Checkout types

interface CheckoutOptions {
  autoRedirect?: boolean;
  locale?: string;
}

interface CheckoutResult {
  success: boolean;
  redirectUrl?: string;
  message?: string;
}

interface CouponValidation {
  valid: boolean;
  discount?: number;
  discount_type?: 'percentage' | 'fixed';
  message?: string;
}

Invoice types

interface Invoice {
  uniqid: string;
  status: string;
  total: number;
  currency: string;
  gateway?: string;
  products: InvoiceProduct[];
  created_at: string;
}

interface InvoiceProduct {
  product_id: string;
  title: string;
  quantity: number;
  price: number;
}

Review types

interface Feedback {
  id: string;
  rating: number;
  comment?: string;
  created_at: string;
}

Error types

class ShoppexError extends Error {
  readonly code: string;
  readonly statusCode?: number;
}

class NotInitializedError extends ShoppexError {
  // Thrown when SDK methods are called before init()
  // code: 'NOT_INITIALIZED'
}

class NetworkError extends ShoppexError {
  // Thrown on HTTP/network failures
  // code: 'NETWORK_ERROR'
}

class ValidationError extends ShoppexError {
  // Thrown on input validation failures
  // code: 'VALIDATION_ERROR'
  readonly invalidFields?: string[];
}

class CartError extends ShoppexError {
  // Thrown on cart operation errors
  // code: 'BASKET_ERROR'
}

Usage with TypeScript

import shoppex, {
  type Product,
  type ProductVariant,
  type CartItem,
  type Invoice,
  type SDKResponse
} from '@shoppexio/storefront';

// Initialize
shoppex.init('my-store');

// Typed responses
async function loadProducts(): Promise<Product[]> {
  const response: SDKResponse<Product[]> = await shoppex.getProducts();

  if (!response.success || !response.data) {
    throw new Error(response.message || 'Failed to load products');
  }

  return response.data;
}

// Type-safe cart operations
function addProductToCart(product: Product, variant?: ProductVariant): void {
  shoppex.addToCart(
    product.uniqid,
    variant?.id ?? '',
    1
  );
}

// Typed invoice handling
async function checkOrderStatus(invoiceId: string): Promise<string> {
  const { data } = await shoppex.getInvoiceStatus(invoiceId);
  return data.status;
}

​Store

​getStore

​getStoreLogoUrl

​getStoreBannerUrl

​Store error handling

​Products

​getProducts

​getProduct

​getCategories

​Product groups

​Working with variants

​Products error handling

​Cart

​getCart

​getCartItemCount

​addToCart

​updateCartItem

​removeFromCart

​clearCart

​Cart backup

​Complete cart UI example

​Checkout

​checkout

​buildCheckoutUrl

​buildCheckoutUrlSync (deprecated)

​Coupons

​Affiliate codes

​Checkout flow

​After checkout

​Reviews and invoices

​getShopReviews

​getInvoice

​getInvoiceStatus

​Formatting utilities

​Types

​Configuration types

​Response types

​Store types

​Product types

​Cart types

​Checkout types

​Invoice types

​Review types

​Error types

​Usage with TypeScript

Store

getStore

getStoreLogoUrl

getStoreBannerUrl

Store error handling

Products

getProducts

getProduct

getCategories

Product groups

Working with variants

Products error handling

Cart

getCart

getCartItemCount

addToCart

updateCartItem

removeFromCart

clearCart

Cart backup

Complete cart UI example

Checkout

checkout

buildCheckoutUrl

buildCheckoutUrlSync (deprecated)

Coupons

Affiliate codes

Checkout flow

After checkout

Reviews and invoices

getShopReviews

getInvoice

getInvoiceStatus

Formatting utilities

Types

Configuration types

Response types

Store types

Product types

Cart types

Checkout types

Invoice types

Review types

Error types

Usage with TypeScript