Cart Management

Get Cart

const cart = await client.cart.get();
// { items, bundleLines, subtotal, discountTotal, grandTotal, currency }

Add Item

productId is the eshop product id of the sellable unit (ProductListItem.id / ProductDetail.id). Each cart line is keyed by that product, and quantity stacks when you add the same product again.

const cart = await client.cart.addItem({
  productId: 'eshop-product-id',
  quantity: 2,
});

// Cart session token is auto-saved internally

Adding a variant

A variant is its own sellable product, so a variant's id (from ProductDetail.variants[].id) is exactly what you pass as productId, and there is no separate variant field:

const {data: product} = await client.catalog.getProduct(slug);
const variant = product.variants.find((v) => v.sku === chosenSku);

await client.cart.addItem({productId: variant.id, quantity: 1});

Linking a cart line back to the product (SDK 1.1.0)

item.product.slug is the slug of the page the line belongs to. For a variant line that is the parent's slug, and item.product.variantSlug holds the deep-link token, because a variant has no page of its own:

import {variantHref} from '@behio/storefront-sdk';

<a href={variantHref(item.product.slug, {variantSlug: item.product.variantSlug ?? ''})}>
  {item.product.name}
</a>

Before 1.1.0 the API returned the variant's own slug here and the link answered 404 for every variant line. item.product.name also now follows the cart's language (Eshop_Cart_Session.locale) instead of an arbitrary translation row.

Update Quantity

const cart = await client.cart.updateQuantity('cart-item-id', 3);

Remove Item

const cart = await client.cart.removeItem('cart-item-id');

Clear Cart

await client.cart.clear();

Switch Cart Currency (SDK 1.6.0)

The cart holds price snapshots in its own currency. Switching the shop currency therefore has two halves: client.setCurrency('EUR') changes what the catalog displays, and client.cart.setCurrency('EUR') re-prices the cart server-side. When you use useCurrency() or <CurrencySwitcher/> from @behio/storefront-sdk/react, both happen automatically.

const result = await client.cart.setCurrency('EUR');

Rules the backend enforces:

• The currency must be one of the shop's supportedCurrencies, otherwise 400.
• Every cart line must have a price configured in the new currency. Money is never FX-converted. If any item lacks one, the call returns 400 with the item names and the cart keeps its previous currency and prices.
• When no cart exists yet, an empty cart is created in the requested currency, so items added later are priced correctly from the start.

Bundles in Cart

Bundles are a separate cart concept from items. The cart exposes them as cart.bundleLines (each with its own id, quantity, bundlePriceSnapshot and the items it contains), and their totals are already included in cart.subtotal / cart.grandTotal. Manage a bundle line by its line id (cart.bundleLines[].id), not the bundle id.

// Add a bundle by slug or id
const cart = await client.cart.addBundle({slug: 'starter-kit'}, 1);

// Read the lines
const line = cart.data?.bundleLines[0];

// Update quantity / remove, always with the bundle LINE id
await client.cart.updateBundleQuantity(line.id, 2);
await client.cart.removeBundle(line.id);

Cart Merge

After login, merge the anonymous cart into the customer cart:

await client.auth.login({ email, password });
const mergedCart = await client.cart.merge();

Session Persistence

// Save to cookie / localStorage
const token = client.getCartSession();

// Restore on page load
client.setCartSession(savedToken);

Events

client.on('cart:updated', (cart) => {
  updateCartBadge(cart.items.length);
});

client.on('cart:cleared', () => {
  updateCartBadge(0);
});