> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craveup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Cart

> Add, update, and remove items in a Crave cart with modifier selections.

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

<Steps>
  <Step title="Start an ordering session">
    Creates a cart and returns a `cartId` you use for all subsequent operations.
  </Step>

  <Step title="Add items">
    Add products with quantities and modifier selections.
  </Step>

  <Step title="Update items">
    Change quantities or remove individual items.
  </Step>

  <Step title="Apply discounts">
    Optionally apply a promo code.
  </Step>

  <Step title="Proceed to checkout">
    Set customer details, fulfillment method, and payment.
  </Step>
</Steps>

## Start an ordering session

<CodeGroup>
  ```ts SDK theme={null}
  import { storefront } from '@/lib/storefront';

  const session = await storefront.orderingSessions.start('loc_123', {
    marketplaceId: 'loc_123',
  });

  const cartId = session.cartId;
  ```

  ```bash REST theme={null}
  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"}'
  ```
</CodeGroup>

<Tip>
  Persist the `cartId` in local storage or a cookie so returning users resume their cart.
</Tip>

## Add an item

<CodeGroup>
  ```ts SDK theme={null}
  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"
  ```

  ```bash REST theme={null}
  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"
    }'
  ```
</CodeGroup>

### Add an item with modifiers

Modifiers represent customizations (e.g., size, toppings, extras). Pass them in the `selections` array.

```ts theme={null}
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

<CodeGroup>
  ```ts SDK theme={null}
  const cart = await storefront.cart.get('loc_123', cartId);

  cart.items.forEach((item) => {
    console.log(`${item.name} x${item.quantity} — ${item.totalFormatted}`);
  });
  ```

  ```bash REST theme={null}
  curl -X GET "https://api.craveup.com/api/v1/locations/loc_123/carts/{cartId}" \
    -H "X-API-Key: $CRAVEUP_API_KEY"
  ```
</CodeGroup>

## Update item quantity

```ts theme={null}
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

<CodeGroup>
  ```ts SDK theme={null}
  await storefront.discounts.apply('loc_123', {
    code: 'SAVE10',
    cartId,
  });
  ```

  ```bash REST theme={null}
  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"}'
  ```
</CodeGroup>

### Remove a discount

```ts theme={null}
await storefront.discounts.remove('loc_123', cartId);
```

## Get recommended products

Show upsell suggestions based on the current cart contents.

```ts theme={null}
const recommendations = await storefront.cart.getRecommendations('loc_123', cartId);

recommendations.forEach((product) => {
  console.log(`${product.name} — ${product.price}`);
});
```

## Delete the cart

```ts theme={null}
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

<CardGroup cols={2}>
  <Card title="Checkout Flow" icon="credit-card" href="/guides/checkout-flow">
    Collect customer details and process payments.
  </Card>

  <Card title="Fulfillment Methods" icon="truck" href="/guides/fulfillment-methods">
    Configure delivery, table-side, and room service.
  </Card>
</CardGroup>