Products

Where products come from

getStore() returns every listable product in store.products - use it for grids, search, categories and the cart. See Store Information.
getProduct(idOrSlug) fetches one product, by ID or slug - use it for a product page.
getProductReviews(productId, page) fetches a product’s reviews, a page at a time.

Get one product

async function loadProduct(idOrSlug) {
  const response = await komerza.getProduct(idOrSlug); // e.g. "premium-license", or the product's ID

  if (!response.success) {
    showNotFound(); // unknown, private, or a typo
    return null;
  }

  return response.data;
}

Each call is a fresh request, and a successful one records a product view in the store’s analytics. That’s what you want on a product page, and not in a cart or a grid - look those products up in store.products instead.

The product object

interface Product {
  id: string;
  name: string;
  description: string; // markdown
  slug?: string;
  imageNames: string[]; // file names - see Images
  rating: number;
  order: number; // the merchant's sort order, ascending
  visibility?: number; // only on getStore() products - see Store Information
  isBestSeller?: boolean;
  hideStock?: boolean;
  badges?: { label: string; color?: string; order: number }[];
  variants: Variant[];
}

Every product has at least one variant, and the price lives on the variant, not the product.

interface Variant {
  id: string;
  name: string;
  description?: string;
  cost: number; // the price, in the store's currency
  order: number;
  minimumQuantity: number;
  maximumQuantity: number; // -1 means no limit
  imageNames: string[]; // empty means "use the product's images"
  stock: number; // 0 when stock is hidden - see Stock
  stockMode: number; // 0 counted, 1 not tracked, 2 set by the merchant
  hideStock: boolean;
  isOutOfStock: boolean;
  type: number; // 0 one-time, 1 subscription
  billingInterval?: number; // subscriptions only - see Subscriptions
  customIntervalDays?: number;
  volumeDiscounts: VolumeDiscount[];
  customFields: object[]; // asked for on the hosted checkout
  requireDiscordAuthorization: boolean;
}

The full definitions are on the TypeScript page.

Prices

Sort variants by order and format cost with the store’s formatter:

const formatter = await komerza.createFormatter();
const variants = [...product.variants].sort((a, b) => a.order - b.order);

const prices = variants.map((variant) => variant.cost);
const from = Math.min(...prices);
const to = Math.max(...prices);

const priceText =
  from === to
    ? formatter.format(from)
    : `${formatter.format(from)} - ${formatter.format(to)}`;

Always pass cost to the formatter exactly as it arrives. On a store with adaptive currency the formatter converts it into the shopper’s currency - see Currency formatting.

Stock

Three fields decide what to show:

Field	Use it for
`isOutOfStock`	Whether the variant can be bought. The only flag to disable “Add to cart” on
`hideStock`	The merchant doesn’t want counts shown
`stock`	The count - meaningful only when stock isn’t hidden and is tracked

When a merchant hides stock levels, every variant is sent with stock: 0. Treating stock === 0 as “sold out” makes those products impossible to buy. isOutOfStock already accounts for hidden and untracked stock.

function stockText(variant) {
  if (variant.isOutOfStock) return "Out of stock";
  if (variant.hideStock || variant.stockMode === 1) return "In stock"; // no count to show
  if (variant.stock <= 5) return `Only ${variant.stock} left`;
  return "In stock";
}

Quantity limits

A variant can set a minimum and a maximum quantity per order (maximumQuantity is -1 when there’s none). The cart doesn’t enforce them - checkout does, and refuses an order outside them - so clamp your quantity input:

function clampQuantity(variant, quantity) {
  const max = variant.maximumQuantity === -1 ? Infinity : variant.maximumQuantity;
  return Math.min(Math.max(quantity, variant.minimumQuantity), max);
}

Subscriptions

A subscription variant has type: 1 and a billingInterval:

`billingInterval`	Bills
`0`	Weekly
`1`	Monthly
`2`	Quarterly
`3`	Yearly
`4`	Every `customIntervalDays` days

function billingPeriod(variant) {
  if (variant.billingInterval == null) return ""; // one-time
  if (variant.billingInterval === 4) return `/ ${variant.customIntervalDays} days`;
  return ["/ week", "/ month", "/ quarter", "/ year"][variant.billingInterval];
}

// "$9.99 / month"
const label = `${formatter.format(variant.cost)} ${billingPeriod(variant)}`.trim();

Checkout refuses a cart that mixes subscriptions with one-time products. Give subscriptions a “Subscribe” button that uses buyNow(), which empties the cart first, or tell the buyer before they add one.

Volume pricing

volumeDiscounts holds quantity tiers. The highest tier the quantity reaches applies to every unit:

interface VolumeDiscount {
  quantity: number; // the quantity that unlocks this tier
  discountType: number; // 0 percent off, 1 amount off each unit, 2 fixed unit price
  discountValue: number; // 10 = 10% off; otherwise an amount in the store's currency
}

function unitPrice(variant, quantity) {
  const tier = variant.volumeDiscounts
    .filter((t) => quantity >= t.quantity)
    .sort((a, b) => b.quantity - a.quantity)[0];

  if (!tier) return variant.cost;
  if (tier.discountType === 0) return variant.cost * (1 - tier.discountValue / 100);
  if (tier.discountType === 1) return Math.max(0, variant.cost - tier.discountValue);
  return tier.discountValue; // 2: fixed unit price
}

Use it to show the buyer what they’ll save. The order is still priced on the server: when a coupon is used and disableVolumeDiscountOnCoupon is true, the tiers stop applying.

Custom fields and Discord

customFields are the questions a merchant asks at checkout, and requireDiscordAuthorization means the buyer has to link their Discord account. Komerza’s hosted checkout handles both, so there’s nothing for your storefront to collect. Read them only if you want to tell the buyer what’s coming.

Badges

badges are the labels a merchant pins on a product, such as “New” or “Sale”, each with an optional hex color. isBestSeller marks the product the merchant chose as their best seller.

const badges = [...(product.badges ?? [])].sort((a, b) => a.order - b.order);

for (const badge of badges) {
  const span = document.createElement("span");
  span.textContent = badge.label;
  if (badge.color) span.style.backgroundColor = badge.color;
  badgeList.append(span);
}

Images

imageNames holds file names, not URLs. A variant with no images of its own uses the product’s:

const names = variant.imageNames.length ? variant.imageNames : product.imageNames;
const urls = names.map((name) => `https://ugc.komerza.com/${name}`);

Reviews

const response = await komerza.getProductReviews(product.id, 1);

Parameter	Type	Notes
`productId`	`string`	The product’s ID. A slug doesn’t work here
`page`	`number`	Starts at 1, which is also the default

interface PaginatedApiResponse<Review> {
  success: boolean;
  pages: number; // the total number of pages
  data?: Review[];
  message?: string;
}

interface Review {
  id: string;
  rating: number; // 1 to 5
  reason: string; // the review text, written by the customer
  reply?: string; // the merchant's reply
  dateCreated: string;
}

Reviews carry no reviewer name.

Review text is written by customers. Render it with textContent or your framework’s normal text binding - never innerHTML. A review containing HTML would otherwise run as part of your page. See Security.

async function renderReviews(container, productId, page = 1) {
  const response = await komerza.getProductReviews(productId, page);
  container.replaceChildren();

  if (!response.success || !response.data.length) {
    container.textContent = "No reviews yet";
    return;
  }

  for (const review of response.data) {
    const item = document.createElement("article");

    const stars = document.createElement("div");
    stars.textContent = "★".repeat(review.rating) + "☆".repeat(5 - review.rating);

    const text = document.createElement("p");
    text.textContent = review.reason;

    const date = document.createElement("time");
    date.dateTime = review.dateCreated;
    date.textContent = new Date(review.dateCreated).toLocaleDateString();

    item.append(stars, text, date);

    if (review.reply) {
      const reply = document.createElement("p");
      reply.textContent = `Reply from the store: ${review.reply}`;
      item.append(reply);
    }

    container.append(item);
  }

  if (response.pages > 1) {
    const nav = document.createElement("nav");

    if (page > 1) {
      const previous = document.createElement("button");
      previous.textContent = "Previous";
      previous.onclick = () => renderReviews(container, productId, page - 1);
      nav.append(previous);
    }

    const position = document.createElement("span");
    position.textContent = `Page ${page} of ${response.pages}`;
    nav.append(position);

    if (page < response.pages) {
      const next = document.createElement("button");
      next.textContent = "Next";
      next.onclick = () => renderReviews(container, productId, page + 1);
      nav.append(next);
    }

    container.append(nav);
  }
}

Complete example

A product page at product.html?slug=...:

<!DOCTYPE html>
<html>
  <head>
    <title>Product</title>
    <script src="https://cdn.komerza.com/komerza.min.js"></script>
    <script>
      komerza.init("your-store-id");
    </script>
  </head>
  <body>
    <img id="image" alt="" />
    <h1 id="name"></h1>
    <p id="price"></p>
    <p id="stock"></p>
    <div id="variants"></div>
    <label>
      Quantity
      <input id="quantity" type="number" value="1" min="1" />
    </label>
    <button id="add">Add to cart</button>
    <section id="reviews"></section>

    <script>
      let product;
      let selected;
      let formatter;

      function billingPeriod(variant) {
        if (variant.billingInterval == null) return "";
        if (variant.billingInterval === 4) return ` / ${variant.customIntervalDays} days`;
        return [" / week", " / month", " / quarter", " / year"][variant.billingInterval];
      }

      function stockText(variant) {
        if (variant.isOutOfStock) return "Out of stock";
        if (variant.hideStock || variant.stockMode === 1) return "In stock";
        if (variant.stock <= 5) return `Only ${variant.stock} left`;
        return "In stock";
      }

      function selectVariant(variant) {
        selected = variant;

        document.getElementById("price").textContent =
          formatter.format(variant.cost) + billingPeriod(variant);
        document.getElementById("stock").textContent = stockText(variant);

        const names = variant.imageNames.length ? variant.imageNames : product.imageNames;
        const image = document.getElementById("image");
        image.hidden = names.length === 0;
        if (names.length) image.src = `https://ugc.komerza.com/${names[0]}`;
        image.alt = product.name;

        const quantity = document.getElementById("quantity");
        quantity.min = variant.minimumQuantity;
        quantity.max = variant.maximumQuantity === -1 ? "" : variant.maximumQuantity;
        quantity.value = variant.minimumQuantity;

        document.getElementById("add").disabled = variant.isOutOfStock;
      }

      async function load() {
        const slug = new URLSearchParams(location.search).get("slug");
        const [response, fmt] = await Promise.all([
          komerza.getProduct(slug),
          komerza.createFormatter(),
        ]);

        if (!response.success) {
          document.getElementById("name").textContent = "Product not found";
          return;
        }

        product = response.data;
        formatter = fmt;
        document.getElementById("name").textContent = product.name;

        const variants = [...product.variants].sort((a, b) => a.order - b.order);
        const buttons = document.getElementById("variants");
        for (const variant of variants) {
          const button = document.createElement("button");
          button.textContent = variant.name;
          button.onclick = () => selectVariant(variant);
          buttons.append(button);
        }

        selectVariant(variants[0]);
        renderReviews(document.getElementById("reviews"), product.id);
      }

      document.getElementById("add").onclick = () => {
        const quantity = Number(document.getElementById("quantity").value);
        komerza.addToBasket(product.id, selected.id, quantity);
      };

      async function renderReviews(container, productId) {
        const response = await komerza.getProductReviews(productId);
        if (!response.success) return;

        for (const review of response.data) {
          const text = document.createElement("p");
          text.textContent = `${"★".repeat(review.rating)} ${review.reason}`;
          container.append(text);
        }
      }

      load();
    </script>
  </body>
</html>

Currency Formatting

Prices in the store’s currency, or the shopper’s

Basket

Adding to the cart, and rendering it

Getting Started

Client Library

Where products come from

Get one product

The product object

Prices

Stock

Quantity limits

Subscriptions

Volume pricing

Custom fields and Discord

Badges

Images

Reviews

Complete example

Next

Currency Formatting

Basket

​Where products come from

​Get one product

​The product object

​Prices

​Stock

​Quantity limits

​Subscriptions

​Volume pricing

​Custom fields and Discord

​Badges

​Images

​Reviews

​Complete example

​Next

Currency Formatting

Basket

Where products come from

Get one product

The product object

Prices

Stock

Quantity limits

Subscriptions

Volume pricing

Custom fields and Discord

Badges

Images

Reviews

Complete example

Next