> ## 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 Crave Storefront API from any platform with simple HTTP requests.

The Storefront REST API mirrors what the SDK does under the hood. Use it when you are building native mobile apps, server-side integrations, or working in languages outside the JavaScript ecosystem.

## Base URL & auth

```text theme={null}
Base URL: https://api.craveup.com/api/v1
Header:   X-API-Key: <your_api_key>
```

All storefront endpoints live under `/api/v1/locations/{locationId}` and require a location-specific API key that you generate in the Crave dashboard.

## Example: fetch menus

```bash theme={null}
curl -X GET "https://api.craveup.com/api/v1/locations/loc_123/menus?orderDate=2024-10-10&orderTime=18:30" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json"
```

## Example: create and manage a cart

```bash theme={null}
# Create a cart
curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/carts" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"marketplaceId": "loc_123", "currentCartId": ""}'

# Add an item
curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/carts/cart_456/cart-item" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productId": "prod_margherita", "quantity": 2}'

# Schedule the order
curl -X PUT "https://api.craveup.com/api/v1/locations/loc_123/carts/cart_456/update-order-time" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pickupType": "LATER", "orderDate": "2024-10-11", "orderTime": "18:15"}'
```

## Handling customers & discounts

```bash theme={null}
# Validate customer details before checkout
curl -X PUT "https://api.craveup.com/api/v1/locations/loc_123/cart/cart_456/validate-and-update" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerName": "Jess", "emailAddress": "jess@example.com"}'

# Apply a discount
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"}'
```

> Want to see more endpoints? Jump to the [Storefront REST reference](/api-reference/overview/api-overview).

## Tips for non-JS stacks

* **Retry on 429** – Respect the `X-RateLimit-Reset` header before retrying.
* **Reuse carts** – Persist cart IDs on the client to keep pricing consistent across sessions.
* **Secure API keys** – Store keys server-side and proxy requests when you cannot trust the client (e.g., native mobile apps).
* **Log failures** – The API returns structured error bodies; log them for observability.

When you need a deeper dive into the payloads and responses, explore the API Reference section in the sidebar.