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 Maat, Kleur) and the variants built from them. getProduct() returns it as product.optionSet:

const { product } = await sdk.ecommerce.getProduct('kasteel-shirt');
// product.optionSet = {
//   options:  [ { name: 'Maat', position: 0, values: ['L','XL'] }, … ],
//   variants: [ { uuid, sku, ean, priceCents, pricePretty, stock, available,
//                 image: { url, thumbnail, altText },
//                 optionValues: { Maat: 'L', Kleur: 'Geel' },
//                 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, { Maat: 'L', Kleur: 'Geel' });
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);
});

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)​

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

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();