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

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?, retries?)​

Adds a product, with automatic retry on failure (default 3 attempts). On success it updates the cached cart and broadcasts a cart event.

await sdk.ecommerce.addToCart(productUuid, 2);

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