​
Overview

Crave provides a comprehensive backend API for building custom food ordering applications. This documentation is for developers who want to integrate directly with Crave’s API to create custom storefronts, mobile apps, or other ordering experiences.

​
API Architecture

Crave’s API follows REST principles with JSON request/response format. The API is designed around these core concepts:

​
Core Entities

  • Locations - Restaurant locations with menus, hours, and settings
  • Products - Menu items with pricing, descriptions, and modifiers
  • Carts - Customer shopping carts with items and calculations
  • Orders - Completed orders with payment and fulfillment information
  • Customers - Customer profiles and order history

​
API Endpoints

Base URL: https://api.cravejs.com/api/v1
Storefront Endpoints (API key required):
  • GET /locations/{locationId} - Location details
  • GET /locations/{locationId}/menus - Menu and products
  • POST /locations/{locationId}/carts - Cart management
  • POST /stripe/payment-intent - Payment processing
Admin Endpoints (Enterprise tier only):
  • Order management (Enterprise + beta access)
  • Menu management (Enterprise + beta access)
  • Analytics and reporting (Enterprise + beta access)
Note: Admin endpoints require Enterprise tier subscription and beta access approval.

​
Authentication

​
API Key Authentication

Most storefront operations use API key authentication: 
const response = await fetch('https://api.cravejs.com/api/v1/locations/123', {
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});

​
Session Token Authentication

Administrative operations require session tokens and are available only to Enterprise tier customers with beta access approval. Contact hello@craveup.com for more information.

​
Rate Limiting

  • Limit: 200 requests per 10 minutes per IP address
  • Headers: X-RateLimit-Remaining, X-RateLimit-Reset
  • Exceeded: 429 status code with retry information

​
Data Flow

​
Typical Storefront Flow

  1. Load Location - Get location details and configuration
  2. Load Menu - Fetch products and categories
  3. Manage Cart - Add/update items, apply discounts
  4. Process Payment - Create payment intent, handle checkout
  5. Order Created - Order automatically created on successful payment

​
Example: Loading a Menu

// Get location details
const location = await fetch(`/api/v1/locations/${locationId}`, {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());

// Load menu items
const menu = await fetch(`/api/v1/locations/${locationId}/menus`, {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());

// Menu structure
{
  "categories": [
    {
      "id": "cat_123",
      "name": "Appetizers",
      "products": [
        {
          "id": "prod_456",
          "name": "Wings",
          "price": 1200, // $12.00 in cents
          "description": "Buffalo wings",
          "modifiers": [...]
        }
      ]
    }
  ]
}

​
Error Handling

​
HTTP Status Codes

  • 200 - Success
  • 400 - Bad Request (validation errors)
  • 401 - Unauthorized (invalid API key)
  • 403 - Forbidden (subscription required)
  • 404 - Not Found
  • 429 - Too Many Requests (rate limited)
  • 500 - Internal Server Error

​
Error Response Format

{
  "error": "validation_error",
  "message": "Invalid location ID",
  "details": {
    "field": "location_id",
    "code": "invalid_format"
  }
}

​
Payment Processing

Crave integrates with Stripe for payment processing:
  1. Create Payment Intent - Call Crave API to create Stripe PaymentIntent
  2. Client-side Checkout - Use Stripe.js to handle payment UI
  3. Payment Confirmation - Stripe processes payment securely
  4. Order Creation - Crave automatically creates order on success

​
Webhooks

Webhook notifications are available for Enterprise tier customers for events like:
  • Order status changes
  • Payment confirmations
  • Cart abandonments
Note: Webhook functionality requires Enterprise tier subscription. Contact support for access.

​
Environment Requirements

​
Development

  • Node.js 18+ (for JavaScript/TypeScript)
  • Valid API key from merchant
  • HTTPS for payment processing

​
Production

  • SSL certificate required
  • Environment variables for API keys
  • Error monitoring recommended

​
Next Steps

  1. Authentication Setup - Configure API keys
  2. Quick Start Guide - Build your first storefront
  3. API Reference - Detailed endpoint documentation
  4. Stripe Integration - Payment processing setup

​
Getting API Access

​
Subscription Requirements

All Crave API access requires a paid subscription:
API TypeSubscription RequiredFeatures Included
Storefront APIsAny paid Crave subscriptionMenu browsing, cart management, payment processing, basic customer data
Admin APIsEnterprise tier onlyOrder management, menu editing, analytics, webhooks
Free trialContact supportEvaluation access for development and testing
Note: Some features like customer order history and address management are currently in development and may require additional configuration.

​
Getting Started

To get started with storefront development:
  1. Purchase a Crave subscription or request trial access
  2. Get API keys from dashboard.craveup.com/developers or your merchant partner
  3. Set up your development environment with the provided credentials
  4. Follow the Quick Start Guide to build your first storefront
  5. Refer to the API Reference for detailed endpoint documentation
For Enterprise tier features (admin APIs, webhooks, advanced analytics), contact hello@craveup.com for beta access.