API Overview

Base URLs

Production: https://api.craveup.com/api/v1/storefront
Sandbox:    https://dev-api-43233223.craveup.com/api/v1/storefront

Authorization

The public API does not use a browser API key.

Resource	Authorization
Published merchant, location, menu, product, order-time, gratuity	Anonymous
Guest cart	Purpose-limited `X-Cart-Token` capability
Customer profile, orders, addresses, saved payments, loyalty history	Merchant-bound bearer JWT
Receipt	Customer JWT or purpose-limited `X-Receipt-Token` capability

Private admin and integration credentials belong only in trusted server or CLI environments.

Start an ordering session

curl -X POST "https://api.craveup.com/api/v1/storefront/locations/LOCATION_ID/ordering-sessions" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: session_01JEXAMPLE" \
  -d '{"fulfillmentMethod":"takeout"}'

The response contains cart and, for a newly created guest cart, cartAccessToken. Save the token in tab-scoped storage. The response ETag contains the cart revision.

Mutate the cart

curl -X POST "https://api.craveup.com/api/v1/storefront/locations/LOCATION_ID/carts/CART_ID/items" \
  -H "Content-Type: application/json" \
  -H "X-Cart-Token: CART_CAPABILITY" \
  -H 'If-Match: "cart-0"' \
  -H "Idempotency-Key: item_01JEXAMPLE" \
  -d '{"productId":"PRODUCT_ID","quantity":1,"selections":[],"itemUnavailableAction":"remove_item"}'

Use the returned ETag for the next mutation. A stale revision returns 409 CART_CONFLICT; reload current cart state before offering a retry.

Checkout

POST /locations/{locationId}/carts/{cartId}/payment-session
POST /locations/{locationId}/carts/{cartId}/payments
GET  /locations/{locationId}/carts/{cartId}/order-result
POST /locations/{locationId}/carts/{cartId}/rating
GET  /receipts/{receiptId}

The order result is one of payment_pending, order_pending, completed, or failed. Only completed is success.

Customer authentication

POST /customer/auth/login
POST /customer/auth/verify-otp
GET  /customer
GET  /customer/orders
GET  /customer/addresses
GET  /customer/saved-payments
GET  /customer/locations/{locationId}/loyalty/ledger

Login initiation includes only merchantSlug and the email/phone identifier. OTP verification repeats both values and may include customer profile fields after identity proof, binding the resulting session to one merchant.

Error envelope

{
  "code": "CART_CONFLICT",
  "message": "The cart changed. Refresh it before retrying.",
  "requestId": "req_123",
  "details": {}
}

Common statuses are 400 validation, 401 invalid capability/session, 404 hidden or missing resource, 409 state/revision conflict, 429 rate limit, 503 dependency unavailable, and 500 internal error.

SDK

const crave = createStorefrontClient({
  baseUrl: process.env.NEXT_PUBLIC_CRAVEUP_API_URL!,
  sessionStore,
  getAuthToken,
});

Prefer the SDK for TypeScript storefronts because it owns capability headers, revisions, idempotency defaults, timeouts, and typed errors.

SDK Reference

API Endpoints

Error Codes

Base URLs

Authorization

Start an ordering session

Mutate the cart

Checkout

Customer authentication

Error envelope

SDK

​Base URLs

​Authorization

​Start an ordering session

​Mutate the cart

​Checkout

​Customer authentication

​Error envelope

​SDK

Base URLs

Authorization

Start an ordering session

Mutate the cart

Checkout

Customer authentication

Error envelope

SDK