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

# REST API Essentials

> Call the public Crave Storefront API directly from web, mobile, or server applications.

The public Storefront API is rooted at:

```text theme={null}
https://api.craveup.com/api/v1/storefront
```

Published merchant, location, menu, and product reads are anonymous. A new ordering session returns a cart capability. Send that capability only in `X-Cart-Token` for the matching cart, use the current ETag in `If-Match` for mutations, and give every write an `Idempotency-Key`. Signed-in customer resources use `Authorization: Bearer <customer-jwt>`.

## Fetch a published menu

```bash theme={null}
curl "https://api.craveup.com/api/v1/storefront/locations/loc_123/menus?orderDate=2026-08-08&orderTime=18:30"
```

## Start an ordering session

```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: session_01" \
  -d '{"fulfillmentMethod":"takeout"}'
```

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

Store `cart.id`, `cartAccessToken`, and `cart.revision` together in tab-scoped browser storage or the mobile platform's secure storage.

## Add an item

```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_margherita","quantity":1,"selections":[],"itemUnavailableAction":"remove_item"}'
```

The response includes a new ETag. Use that value for the next mutation. If the API returns `CART_CONFLICT`, fetch the cart with the capability, update local state and revision, and require an explicit user retry.

## Authentication boundaries

| Resource                                                     | Credential                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------- |
| Published catalog                                            | None                                                       |
| Cart and checkout                                            | Matching cart capability                                   |
| Customer profile, orders, addresses, saved payments, loyalty | Customer JWT                                               |
| Public receipt                                               | Receipt capability from the URL fragment or customer JWT   |
| Admin and partner APIs                                       | Server-only credential; never a storefront client variable |

Do not put capabilities, JWTs, receipt tokens, or payment secrets in query strings or logs. Configure the API CORS allowlist with exact production and preview storefront origins.

Explore the [Storefront REST reference](/api-reference/overview/api-overview) for endpoint schemas.