Skip to main content

Ecommerce

The sdk.ecommerce module is the largest part of the SDK. It covers the product catalogue, the shopping cart, checkout information, categories and filters, stock, and address lookups.

All methods return a Promise. Responses are JSON objects; successful responses generally include status: 'success'.

Products​

getProducts(params?)​

Get a paginated list of products.

const result = await sdk.ecommerce.getProducts({
    category: 'shoes',   // optional category slug
    filters: {},         // optional filter map
    page: 1,             // default 1
    limit: 30,           // default 30
    sort: 'popularity',  // default 'popularity'
});
// → { status, products: [...], pagination: {...} }

getProduct(productUuid)​

Get a single product by its UUID or slug.

const { product } = await sdk.ecommerce.getProduct('blue-running-shoe');

fetchRelatedProducts(productUuid)​

const { products } = await sdk.ecommerce.fetchRelatedProducts(productUuid);

Product options & variants​

A product may carry an option set: a list of options (attributes like Size, Colour) and the variants built from them. getProduct() returns it as product.optionSet:

const { product } = await sdk.ecommerce.getProduct('kasteel-shirt');
// product.optionSet = {
//   options:  [ { name: 'Size', position: 0, values: ['L','XL'] }, … ],
//   variants: [ { uuid, sku, ean, priceCents, pricePretty, stock, available,
//                 image: { url, thumbnail, altText },
//                 optionValues: { Size: 'L', Colour: 'Yellow' },
//                 properties: [ { name, value } ], metafields: [ { name, type, value } ] }, … ]
// }

getVariants(productUuid)​

const variants = await sdk.ecommerce.getVariants('kasteel-shirt');

Ecommerce.resolveVariant(optionSet, selectedOptionValues)​

A static helper that returns the variant matching a full selection of option values, or null when the selection is incomplete or unknown:

const variant = Ecommerce.resolveVariant(product.optionSet, { Size: 'L', Colour: 'Yellow' });
if (variant && variant.available) {
    showPrice(variant.pricePretty);
    switchMainImage(variant.image.url); // jump to that option's image
}

Adding a variant to the cart​

Pass the resolved variant's uuid to addToCart:

await sdk.ecommerce.addToCart(product.uuid, 1, variant.uuid);

A plain single product simply has an empty optionSet.variants, and addToCart(productUuid, quantity) works unchanged.

The cart​

The cart is cached on the instance after the first fetch and kept in sync across tabs and instances (see cart events).

getCart(forceRefresh?)​

const cart = await sdk.ecommerce.getCart();       // cached if already loaded
const fresh = await sdk.ecommerce.getCart(true);  // bypass the cache
// → { status, currency, items, products, bundles, total_amount, total_products }

addToCart(productUuid, quantity?, variantUuid?, retries?)​

Adds a product, with automatic retry on failure (default 3 attempts). On success it updates the cached cart and broadcasts a cart event. Pass variantUuid to add a specific option variant; leave it out for a plain single product.

await sdk.ecommerce.addToCart(productUuid, 2);                 // single product
await sdk.ecommerce.addToCart(productUuid, 1, variant.uuid);   // a chosen variant

updateCartQuantity(productUuid, quantity)​

await sdk.ecommerce.updateCartQuantity(productUuid, 3);

clearCart()​

await sdk.ecommerce.clearCart();

Cart events​

Every mutating call emits sitepack:cart:updated on window:

window.addEventListener('sitepack:cart:updated', (e) => {
    const { cart, source } = e.detail; // source: 'local' (this tab) | 'sync' (another tab)
    updateCartUI(cart);
});

Next to the whole cart, the SDK reports what changed: sitepack:cart:added carries the lines whose quantity went up and sitepack:cart:removed the lines whose quantity went down (detail.items, each with the quantity that changed, plus detail.cart). createOrder() emits sitepack:order:created before the browser leaves for the payment provider; once the order is paid, the confirmation page raises sitepack:checkout:thank-you ({order}), the paid counterpart of order:created — the SDK raises it for you, so you only listen. All of these carry detail.source === 'sdk'; the full list of storefront events is in Storefront Blocks & Events.

Checkout information​

getCheckoutInfo(data?)​

Returns payment methods, shipping methods and countries, and price totals for the current cart.

const info = await sdk.ecommerce.getCheckoutInfo({
    country: 'NL',            // optional; falls back to the site default
    delivery_method: 'default'
});
// → { methods, shipping_methods, shipping_countries,
//     shipping_costs_cents, discount_price_cents, total_price_cents, coupons, ... }
Prices are in cents

Fields ending in _cents are integers. Divide by 100 and format for display.

claimCoupon(couponCode)​

Applies a coupon to the current cart.

await sdk.ecommerce.claimCoupon('SUMMER10');

fetchAddress(countryCode, postalCode, number)​

Resolves a full address from a postal code and house number — ideal for checkout auto-fill.

const address = await sdk.ecommerce.fetchAddress('NL', '1011AB', '10');
// → { status, street, city, country_code }

Categories & filters​

getCategories()​

const { categories } = await sdk.ecommerce.getCategories();

getFilters(categorySlug)​

const { filters } = await sdk.ecommerce.getFilters('shoes');

Stock & availability​

getStockInfo(productUuid, forceRefresh?)​

const { data } = await sdk.ecommerce.getStockInfo(productUuid);
// data → { allowBackorder, deliveryDate, inStock, quantityAvailable, quantitySupplier }

You can call it once per product card without worrying about the rate limit: the calls a page makes in the same tick go out as one batched request (up to 50 products each), and a product already asked for on the page is answered from memory. Pass forceRefresh to ask the API again. Each call still resolves to the single-product shape above, and rejects when the stock of that product is unknown.

document.querySelectorAll('[data-stock-product]').forEach(async (el) => {
    try {
        const { data } = await sdk.ecommerce.getStockInfo(el.dataset.stockProduct);
        el.textContent = data.inStock ? 'In stock' : 'Out of stock';
    } catch {
        // Unknown stock: keep the line the template rendered.
    }
});

checkOrderCapability(productUuid, forceRefresh?)​

Returns whether a product can currently be ordered. The result is cached per product on the instance.

const { available } = await sdk.ecommerce.checkOrderCapability(productUuid);
if (!available) disableBuyButton();