This guide covers the full cart lifecycle — from creating a session to adding items with modifiers, updating quantities, applying discounts, and clearing the cart.
Cart lifecycle overview
Start an ordering session
Creates a cart and returns a cartId you use for all subsequent operations.
Add items
Add products with quantities and modifier selections.
Update items
Change quantities or remove individual items.
Apply discounts
Optionally apply a promo code.
Proceed to checkout
Set customer details, fulfillment method, and payment.
Start an ordering session
import { storefront } from '@/lib/storefront';
const session = await storefront.orderingSessions.start('loc_123', {
marketplaceId: 'loc_123',
});
const cartId = session.cartId;
Persist the cartId in local storage or a cookie so returning users resume their cart.
Add an item
const result = await storefront.cart.addItem('loc_123', cartId, {
productId: 'prod_margherita',
quantity: 2,
selections: [],
itemUnavailableAction: 'remove_item',
});
console.log(result.cart.totalQuantity); // e.g. 2
console.log(result.cart.orderTotalWithServiceFeeFormatted); // e.g. "$25.98"
Add an item with modifiers
Modifiers represent customizations (e.g., size, toppings, extras). Pass them in the selections array.
await storefront.cart.addItem('loc_123', cartId, {
productId: 'prod_burger',
quantity: 1,
itemUnavailableAction: 'remove_item',
selections: [
{
groupId: 'mod_size',
selectedOptions: [
{ optionId: 'opt_large', quantity: 1 }
],
},
{
groupId: 'mod_toppings',
selectedOptions: [
{ optionId: 'opt_bacon', quantity: 1 },
{ optionId: 'opt_cheese', quantity: 2 },
],
},
],
});
Item unavailable actions
When an item becomes unavailable after being added (e.g., sold out), Crave handles it based on the itemUnavailableAction field:
| Action | Behavior |
|---|
remove_item | Remove the specific item from the cart |
cancel_entire_order | Cancel the whole order if any item is unavailable |
Get the cart
const cart = await storefront.cart.get('loc_123', cartId);
cart.items.forEach((item) => {
console.log(`${item.name} x${item.quantity} — ${item.totalFormatted}`);
});
Update item quantity
await storefront.cart.updateItemQuantity(
'loc_123',
cartId,
'cart_item_abc', // the cart item ID (from cart.items[].id)
3 // new quantity
);
0 to remove the item.
Apply a discount
await storefront.discounts.apply('loc_123', {
code: 'SAVE10',
cartId,
});
Remove a discount
await storefront.discounts.remove('loc_123', cartId);
Get recommended products
Show upsell suggestions based on the current cart contents.
const recommendations = await storefront.cart.getRecommendations('loc_123', cartId);
recommendations.forEach((product) => {
console.log(`${product.name} — ${product.price}`);
});
Delete the cart
await storefront.cart.delete('loc_123', cartId);
Cart data model
The StorefrontCart type includes these key fields:
| Field | Type | Description |
|---|
id | string | Unique cart ID |
items | CartItem[] | Line items with quantity, modifiers, price |
totalQuantity | number | Sum of all item quantities |
subTotal | string | Pre-tax, pre-fee subtotal |
taxTotal | string | Calculated tax |
orderTotalWithServiceFee | string | Final total including all fees |
discountCode | string | null | Applied promo code |
fulfilmentMethod | string | Current fulfillment method |
pickupType | 'ASAP' | 'LATER' | Order timing |
currency | string | Cart currency (usd, gbp, etc.) |
Next steps
