The sdk.cart namespace manages the shopping cart. Cart operations work for both authenticated customers and guest visitors. The SDK automatically handles cart token management — tokens are extracted from API responses and sent with subsequent requests via the X-Cart-Token header.
Methods
cart.get()
Retrieve the current cart contents.
const cart = await sdk.cart.get();
console.log(cart.items); // CartItem[]
console.log(cart.total); // number
console.log(cart.currency); // string
Cart
interface Cart {
items: CartItem[];
count: number;
subtotal: number;
total: number;
currency: string;
}
interface CartItem {
id: number;
product_id: number;
product: Product;
quantity: number;
price: number;
total: number;
}
cart.addItem(productId, quantity?, options?)
Add a product to the cart.
// Add 1 unit
const cart = await sdk.cart.addItem(productId);
// Add 2 units with custom fields
const cart = await sdk.cart.addItem(productId, 2, {
fields: { color: 'red', size: 'L' },
notice: 'Gift wrap please'
});
| Field | Type | Default | Description |
|---|
productId | number | — | Product ID to add |
quantity | number | 1 | Quantity to add |
options.fields | Record<string, any> | — | Custom product fields (variants, options) |
options.notice | string | — | Special instructions or notes |
Cart
cart.updateItem(itemId, quantity)
Update the quantity of a cart item.
await sdk.cart.updateItem(itemId, 3);
| Field | Type | Description |
|---|
itemId | string | Cart item ID |
quantity | number | New quantity |
Cart
cart.removeItem(itemId)
Remove an item from the cart.
await sdk.cart.removeItem(itemId);
Cart
cart.clear()
Remove all items from the cart and clear the stored cart token.
Returns: void
cart.getCount()
Get the number of items in the cart without fetching the full cart.
const count = await sdk.cart.getCount();
// 3
number
cart.applyCoupon(code)
Apply a discount coupon to the cart.
const cart = await sdk.cart.applyCoupon('DISCOUNT10');
| Field | Type | Description |
|---|
code | string | Coupon code |
Cart
If the coupon is invalid or expired, the API returns an error. Wrap this call in a try/catch to display the error message to the customer.
cart.removeCoupon()
Remove the currently applied coupon.
const cart = await sdk.cart.removeCoupon();
Cart
cart.validate()
Check whether the current cart contents are valid for checkout (e.g., all items in stock, no conflicts).
const validation = await sdk.cart.validate();
if (!validation.valid) {
console.error('Cart issues:', validation.errors);
}
{ valid: boolean; errors?: string[] }
cart.getSummary()
Get the cart totals breakdown without fetching individual items.
const summary = await sdk.cart.getSummary();
// { subtotal: 100, tax: 15, shipping: 0, discount: 10, total: 105 }
{
subtotal: number;
tax: number;
shipping: number;
discount: number;
total: number;
}
Cart Token Management
The SDK manages cart tokens automatically, but you can also control them manually:
// Set a cart token (e.g., restored from localStorage)
sdk.setCartToken('cart_abc123');
// Read the current cart token
const token = sdk.getCartToken();
// Clear the cart token
sdk.setCartToken(null);
For guest users, persist the cart token in localStorage so the cart survives page reloads:// After any cart operation
const token = sdk.getCartToken();
if (token) localStorage.setItem('rmz_cart_token', token);
// On app initialization
const saved = localStorage.getItem('rmz_cart_token');
if (saved) sdk.setCartToken(saved);
Example: Add to Cart Flow
try {
const cart = await sdk.cart.addItem(product.id, quantity, {
fields: selectedOptions,
});
// Cart token is automatically stored by the SDK
console.log(`Cart now has ${cart.count} items, total: ${cart.total} ${cart.currency}`);
} catch (error) {
// Handle errors (out of stock, invalid product, etc.)
console.error('Failed to add item:', error.message);
}
