Manage Cart

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;

curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/ordering-sessions" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"marketplaceId": "loc_123"}'

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"

curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/carts/{cartId}/cart-item" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_margherita",
    "quantity": 2,
    "selections": [],
    "itemUnavailableAction": "remove_item"
  }'

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}`);
});

curl -X GET "https://api.craveup.com/api/v1/locations/loc_123/carts/{cartId}" \
  -H "X-API-Key: $CRAVEUP_API_KEY"

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,
});

curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/discounts/apply-discount" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "SAVE10", "cartId": "cart_456"}'

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.)

Cart lifecycle overview

Start an ordering session

Add an item

Add an item with modifiers

Item unavailable actions

Get the cart

Update item quantity

Apply a discount

Remove a discount

Get recommended products

Delete the cart

Cart data model

Next steps

Checkout Flow

Fulfillment Methods

​Cart lifecycle overview

​Start an ordering session

​Add an item

​Add an item with modifiers

​Item unavailable actions

​Get the cart

​Update item quantity

​Apply a discount

​Remove a discount

​Get recommended products

​Delete the cart

​Cart data model

​Next steps

Checkout Flow

Fulfillment Methods

Cart lifecycle overview

Start an ordering session

Add an item

Add an item with modifiers

Item unavailable actions

Get the cart

Update item quantity

Apply a discount

Remove a discount

Get recommended products

Delete the cart

Cart data model

Next steps