Products API

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.

Product prices are returned as string types to preserve decimal precision. Always use shoppex.formatPrice() for display — do not perform arithmetic directly on price strings.

string

Currency code (ISO 4217)

string

URL-friendly product identifier

string

Full product description (HTML)

{ title: string; content: string }[]

Merchant-defined extra description tabs (e.g. 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 (e.g., size, color)

ProductAddon[]

Optional add-ons

PriceVariant[]

Price-based variants (e.g., subscription tiers)

CustomFieldDefinition[]

Custom input fields for checkout

number

Available stock quantity

ProductCategory[]

Product categories as objects with uniqid and title

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, you should 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"]

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 (e.g. “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 will see 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, and /v1/storefront/products/shop/:name 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 like size or color that don’t 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
});

Error Handling

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

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

Getting Started

API Reference

Resources

getProducts

Response

Example: Product Grid

getProduct

Parameters

Example: Product Detail Page

getCategories

Example: Category Filter

Product Groups

Group object

Resolving group products

Working with Variants

Standard Variants

Price Variants

Addons

Error Handling

Next Steps

Cart API

Store API

​getProducts

​Response

​Example: Product Grid

​getProduct

​Parameters

​Example: Product Detail Page

​getCategories

​Example: Category Filter

​Product Groups

​Group object

​Resolving group products

​Working with Variants

​Standard Variants

​Price Variants

​Addons

​Error Handling

​Next Steps

Cart API

Store API

getProducts

Response

Example: Product Grid

getProduct

Parameters

Example: Product Detail Page

getCategories

Example: Category Filter

Product Groups

Group object

Resolving group products

Working with Variants

Standard Variants

Price Variants

Addons

Error Handling

Next Steps