Skip to main content
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

1

Start an ordering session

Creates a cart and returns a cartId you use for all subsequent operations.
2

Add items

Add products with quantities and modifier selections.
3

Update items

Change quantities or remove individual items.
4

Apply discounts

Optionally apply a promo code.
5

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:
ActionBehavior
remove_itemRemove the specific item from the cart
cancel_entire_orderCancel 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
);
Set quantity to 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);
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:
FieldTypeDescription
idstringUnique cart ID
itemsCartItem[]Line items with quantity, modifiers, price
totalQuantitynumberSum of all item quantities
subTotalstringPre-tax, pre-fee subtotal
taxTotalstringCalculated tax
orderTotalWithServiceFeestringFinal total including all fees
discountCodestring | nullApplied promo code
fulfilmentMethodstringCurrent fulfillment method
pickupType'ASAP' | 'LATER'Order timing
currencystringCart currency (usd, gbp, etc.)

​
Next steps

Checkout Flow

Collect customer details and process payments.

Fulfillment Methods

Configure delivery, table-side, and room service.