Products API

Fetch products, variants, and categories

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

data · Product[]

Array of products

Show Product object

uniqid · string

Unique product identifier

title · string

Product name

price · 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.

currency · string

Currency code (ISO 4217)

slug · string

URL-friendly product identifier

description · string

Full product description (HTML)

images · ProductImage[]

Array of product images

cdn_image_url · string | null

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

detail_image_url · string | null

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

youtube_link · string | null

Optional product video URL (YouTube, Vimeo, or other supported embed providers). null when no video is configured.

variants · ProductVariant[]

Available variants (e.g., size, color)

addons · ProductAddon[]

Optional add-ons

price_variants · PriceVariant[]

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

custom_fields · CustomFieldDefinition[]

Custom input fields for checkout

stock · number

Available stock quantity

categories · 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

idOrSlug · 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.youtube_link ? `
        <div class="product-video">
          <iframe src="${product.youtube_link.replace('watch?v=', 'embed/')}" 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);
}

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
}

---

Next Steps

Cart API

Add products to the shopping cart

Store API

Fetch store metadata and branding