Cart data

Use this page when you build a mini-cart, a cart page or a checkout banner and need to know what the cart contains and what each field means.

Read itCopy Anchor Link

The cart lives in the browser: the cart id is stored there, so the server cannot load it. Ask the Salla SDK for the id, then fetch the cart with the cart API module.

import { useEffect, useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { cart } from '@salla.sa/twilight-theme-engine/api/cart';
import { useMoney } from '@salla.sa/twilight-theme-engine/hooks/useMoney';

export function MiniCart() {
  const { format } = useMoney();
  const [cartId, setCartId] = useState<number | null>(null);

  useEffect(() => {
    window.salla?.cart.api.getCurrentCartId().then(setCartId);
  }, []);

  const { data } = useQuery({ ...cart.queries.detail(cartId!), enabled: !!cartId });

  if (!data) return null; // no cart yet, or still loading
  return (
    <p>
      {data.items.length} items, {format(data.total)}
    </p>
  );
}

The built-in cart page does exactly this and shows a skeleton until the cart arrives. To follow changes live, listen to cart events (React to cart events) and invalidate the query.

The Cart objectCopy Anchor Link

Example (illustrative values):

The tables are generated from Cart in @salla.sa/twilight-theme-engine/types. Nested objects get their own tables: items (the lines), their options, offers and attachments, and free_shipping_bar. Example values are in the explorer above.

itemsCopy Anchor Link

items.offerCopy Anchor Link

items.attachmentsCopy Anchor Link

items.optionsCopy Anchor Link

free_shipping_barCopy Anchor Link

optionsCopy Anchor Link

Same fields as items.options.

giftCopy Anchor Link

loyaltyCopy Anchor Link

loyalty.prizeCopy Anchor Link

All amounts are in the store's currency. Format them with useMoney, see Money.

Use a line's id to update or remove it, not product_id. CartItemOption belongs to a line (a size, a colour, a text field); CartOption is an order-level option on cart.options, with the same shape. loyalty and gift are top-level in the API response; the engine copies them onto the cart object.

Common tasksCopy Anchor Link

Show the free-shipping progress:

const bar = cart.free_shipping_bar;
if (bar && !bar.has_free_shipping) {
  return <progress max={100} value={bar.percent} />;
}

Read a price that may be a number or a Money object:

import type { Money } from '@salla.sa/twilight-theme-engine/types';

const amount = (value: number | Money) => (typeof value === 'number' ? value : value.amount);

Change the cart with the Salla SDK, then let the query refresh:

await window.salla?.cart.addItem(productId, 1);
await window.salla?.cart.updateItem({ id: item.id, quantity: 3 });
await window.salla?.cart.deleteItem(item.id);

Apply or remove a coupon with useCoupon:

import { useCoupon } from '@salla.sa/twilight-theme-engine/hooks/useCoupon';

const { value, apply, remove, error, loading } = useCoupon();
await apply('SAVE10'); // resolves true on success, false on failure; `error` holds the message
// `value` starts as null on every page load: read the applied code from `cart.coupon`

Share the cart with child componentsCopy Anchor Link

CartContextProvider and useCartContext carry a cart down your component tree so you do not pass it through every level.

import { CartContextProvider, useCartContext } from '@salla.sa/twilight-theme-engine/contexts';

function Count() {
  const ctx = useCartContext(); // null outside a provider
  return <span>{ctx?.cart.count ?? 0}</span>;
}

// <CartContextProvider value={{ cart }}><Count /></CartContextProvider>

GotchasCopy Anchor Link

• price, product_price, total and the other line amounts can be numbers or Money objects. Do not assume one.
• Cart id is a string in the object, but the API call takes a number (cart.queries.detail(cartId)).
• After an SDK change, the cached cart is stale until you invalidate it. See the cart API module.
• loyalty is top-level in the API response and is placed on the cart object for you. gift already arrives inside the cart.
• free_shipping_bar, coupon, total_discount and the item offer are often absent. Guard each one.

NextCopy Anchor Link

• Cart route and cart slots for the cart page.
• Shared types for Money.
• React to cart events