Basket

How the basket works

The basket lives in the visitor’s browser (localStorage), so it survives reloads and is shared by every tab on your site. Every basket function is synchronous and takes effect immediately. It stores IDs and quantities, nothing else:

interface BasketItem {
  productId: string;
  variantId: string;
  quantity: number;
}

To show names, images and prices, look the items up in store.products - see Render a cart.

Add to the basket

komerza.addToBasket(productId, variantId, quantity);

Parameter	Type	Notes
`productId`	`string`
`variantId`	`string`	Required, even for a product with a single variant
`quantity`	`number`	Optional, defaults to 1. 0 or less is ignored

Adding a variant that’s already in the basket increases its quantity rather than adding a second line.

Buy now

komerza.buyNow(productId, variantId, quantity);

Empties the basket, then adds this one item. It doesn’t open checkout by itself - send the buyer straight on to your checkout form. It’s the simple way to sell a subscription, since those can’t share a cart with one-time products.

Change a quantity

komerza.setBasketItemQuantity(productId, variantId, 3);

Sets the quantity of an item that’s already in the basket. 0 or less removes it. An item that isn’t in the basket is ignored - use addToBasket() for that.

Remove and clear

komerza.removeFromBasket(productId, variantId); // one line, whatever its quantity
komerza.clearBasket(); // everything

Read the basket

const items = komerza.getBasket(); // BasketItem[]
const count = komerza.getBasketItemCount(); // the sum of every line's quantity

React to changes

const stop = komerza.on("basketchange", (event) => {
  // event.items - the basket after the change
  // event.itemCount - what getBasketItemCount() would return
  document.getElementById("cart-count").textContent = event.itemCount;
});

// Later, if the element goes away:
stop();

basketchange fires after every change to the basket, whether this page made it or another tab did. It doesn’t fire when nothing changed, such as removing an item that wasn’t there. It’s the event to build a cart badge or a cart drawer on.

The browser’s own storage event isn’t a substitute: it fires in other tabs, never in the one that made the change.

In React, subscribe in an effect and return the unsubscribe function as the cleanup:

import { useEffect, useState } from "react";

export function useBasket() {
  const [items, setItems] = useState(() => komerza.getBasket());

  useEffect(() => komerza.on("basketchange", (event) => setItems(event.items)), []);

  return items;
}

Render a cart

The basket holds IDs, so join them with store.products - which includes unlisted products too, so a buyer who added one from a direct link still sees it. Don’t call getProduct() for each line: that’s a request per line, and each one records a product view in the store’s analytics.

async function renderCart(container) {
  const [response, formatter] = await Promise.all([
    komerza.getStore(),
    komerza.createFormatter(),
  ]);
  if (!response.success) return;

  const products = response.data.products;
  container.replaceChildren();

  for (const item of komerza.getBasket()) {
    const product = products.find((p) => p.id === item.productId);
    const variant = product?.variants.find((v) => v.id === item.variantId);

    // The merchant removed it, or it's private now: drop it rather than fail at checkout
    if (!variant) {
      komerza.removeFromBasket(item.productId, item.variantId);
      continue;
    }

    const row = document.createElement("div");

    const name = document.createElement("span");
    name.textContent =
      product.variants.length > 1 ? `${product.name} - ${variant.name}` : product.name;

    const quantity = document.createElement("input");
    quantity.type = "number";
    quantity.min = variant.minimumQuantity;
    if (variant.maximumQuantity !== -1) quantity.max = variant.maximumQuantity;
    quantity.value = item.quantity;
    quantity.onchange = () =>
      komerza.setBasketItemQuantity(product.id, variant.id, Number(quantity.value));

    const price = document.createElement("span");
    price.textContent = formatter.format(variant.cost * item.quantity);

    const remove = document.createElement("button");
    remove.textContent = "Remove";
    remove.onclick = () => komerza.removeFromBasket(product.id, variant.id);

    row.append(name, quantity, price, remove);
    container.append(row);
  }

  if (!container.children.length) {
    container.textContent = "Your cart is empty";
  }
}

const cart = document.getElementById("cart");
renderCart(cart);
komerza.on("basketchange", () => renderCart(cart));

What the basket doesn’t check

The basket accepts whatever you put in it. Checkout is where the rules are enforced, and it refuses an order that breaks one:

Stock - disable “Add to cart” when variant.isOutOfStock is true
Quantity limits - keep quantities between minimumQuantity and maximumQuantity
Subscriptions - a subscription can’t share an order with one-time products

Checking these in your UI means buyers find out while they shop, not when they pay.

Where the basket is kept

The basket belongs to the browser and your site’s origin. It isn’t synced across devices or browsers, and it isn’t tied to a store: if you develop several stores on the same localhost port, they share one basket. Call clearBasket() when you switch.

Advanced

These are rarely needed, but they’re part of the API.

Backups

komerza.createBasketBackup(); // true if saved
komerza.restoreBasketFromBackup(); // true if the backup was restored

The SDK saves a backup by itself whenever the page is hidden or closed. A restore only happens if the basket is empty or the backup is newer than it, so it can’t overwrite a basket the buyer has changed since. You don’t need a backup around checkout: checkout() never changes the basket.

Merge

const merged = komerza.mergeBaskets(savedItems);

Merges another list of items - one you saved on your own server, say - into the basket and saves the result. When both contain the same product and variant, the higher quantity wins; quantities aren’t added together. Lines without a product ID or with a quantity of 0 or less are skipped. Returns the basket after the merge.

Move

komerza.moveBasketItem(productId, fromVariantId, productId, toVariantId); // true if moved

Moves a line’s whole quantity to another product or variant - handy when the buyer switches variant in the cart. If the destination is already in the basket, the quantities are combined. Returns false when the source line isn’t there.

Integrity and stats

komerza.validateBasketIntegrity(); // false if the stored basket was changed outside the SDK
komerza.getBasketStats();
// {
//   itemCount: 2,          distinct lines
//   totalQuantity: 3,      sum of quantities
//   lastModified: 1760000000000,
//   version: 14,           increases with every change
//   hasBackup: true,
//   integrityValid: true
// }

Checkout

Turning the basket into an order

Products

Stock, limits and subscriptions

Getting Started

Client Library

How the basket works

Add to the basket

Buy now

Change a quantity

Remove and clear

Read the basket

React to changes

Render a cart

What the basket doesn’t check

Where the basket is kept

Advanced

Backups

Merge

Move

Integrity and stats

Next

Checkout

Products

​How the basket works

​Add to the basket

​Buy now

​Change a quantity

​Remove and clear

​Read the basket

​React to changes

​Render a cart

​What the basket doesn’t check

​Where the basket is kept

​Advanced

​Backups

​Merge

​Move

​Integrity and stats

​Next

Checkout

Products

How the basket works

Add to the basket

Buy now

Change a quantity

Remove and clear

Read the basket

React to changes

Render a cart

What the basket doesn’t check

Where the basket is kept

Advanced

Backups

Merge

Move

Integrity and stats

Next