> ## 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

> Create and mutate a cart with capability, revision, and idempotency protection.

Every cart has three values that belong together: `cart.id`, the secret `cartAccessToken`, and the current `cart.revision`. The SDK persists them through the `sessionStore` you provide.

## Start a session

```ts theme={null}
const session = await storefront.orderingSessions.start("loc_123", {
  marketplaceId: "web",
  fulfillmentMethod: "takeout",
});

const cartId = session.cart.id;
```

```bash theme={null}
curl -X POST "https://api.craveup.com/api/v1/storefront/locations/loc_123/ordering-sessions" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: start_01" \
  -d '{"marketplaceId":"web","fulfillmentMethod":"takeout"}'
```

`marketplaceId` is optional source attribution, such as `"web"` or
`"mobile"`; it is not a location ID. The route already supplies the location
scope.

Store the response capability in `sessionStorage` for browsers or secure device storage for mobile. Do not use a URL, cookie shared across origins, analytics property, or application log.

## Add an item

```ts theme={null}
const cart = 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 }],
    },
  ],
});
```

```bash theme={null}
curl -X POST "https://api.craveup.com/api/v1/storefront/locations/loc_123/carts/cart_456/items" \
  -H "Content-Type: application/json" \
  -H "X-Cart-Token: $CART_ACCESS_TOKEN" \
  -H 'If-Match: "cart-0"' \
  -H "Idempotency-Key: add_item_01" \
  -d '{"productId":"prod_burger","quantity":1,"selections":[],"itemUnavailableAction":"remove_item"}'
```

## Read and mutate the cart

```ts theme={null}
const current = await storefront.cart.get("loc_123", cartId);
await storefront.cart.updateItemQuantity("loc_123", cartId, "item_abc", 2);
await storefront.cart.removeItem("loc_123", cartId, "item_abc");
await storefront.cart.applyDiscount("loc_123", cartId, "SAVE10", {
  includeCustomerContext: true,
});
await storefront.cart.removeDiscount("loc_123", cartId);
```

The SDK sends the capability automatically. For raw REST calls, send `X-Cart-Token` on every cart read and write. Send `If-Match` and a stable `Idempotency-Key` on every mutation.

Pass `includeCustomerContext: true` only when a signed-in shopper still has a
guest-capability cart and discount validation needs customer context. Omit it
for a guest; a claimed cart uses the customer JWT automatically.

## Handle conflicts safely

The API returns `CART_CONFLICT` when `If-Match` is stale. The SDK refreshes the stored revision but deliberately does not repeat the failed mutation. Replace the UI cart with the fresh server state, explain the change, and require the user to retry.

## End the capability lifecycle

`cart.delete()` clears the SDK session. `cart.claim()` removes the guest capability while retaining the authoritative revision for customer-authenticated access. After checkout reaches `completed` or `failed`, clear the persisted capability once terminal handling such as a same-page rating is finished.

<CardGroup cols={2}>
  <Card title="Checkout Flow" icon="credit-card" href="/guides/checkout-flow">
    Protect payment creation and order-result polling.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/guides/error-codes">
    Handle authorization and concurrency failures.
  </Card>
</CardGroup>