API Overview

​

What is the Crave Storefront API?

​

Base URL

https://api.cravejs.com/api/v1

Note: There is no local development server for the Crave API. All storefront applications connect directly to the production API using your API key.

​

Authentication

const headers = {
  'X-API-Key': 'your_api_key_here',
  'Content-Type': 'application/json'
};

​

API Capabilities

​

What You Can Do

• Browse Menus: Get location information, menus, and products
• Manage Carts: Create and manage shopping carts with automatic pricing
• Process Payments: Create payment intents and handle checkout
• Configure Orders: Set delivery addresses, tips, and order times
• Apply Discounts: Apply and remove discount codes

​

What You Cannot Do

• Order Management: View or modify existing orders
• Menu Management: Create or edit menus
• Customer Accounts: Persistent customer accounts or order history
• Real-time Updates: Live order tracking or status updates
• Admin Functions: Analytics, reporting, or merchant settings

​

API Structure

​

Location-Scoped Operations

// All endpoints follow this pattern:
/api/v1/locations/{locationId}/...

// Examples:
GET /api/v1/locations/downtown-pizza/menus
POST /api/v1/locations/downtown-pizza/carts
GET /api/v1/locations/downtown-pizza/products

​

Resource Groups

• Locations: Restaurant location information and settings
• Menus: Menu categories and products
• Products: Individual menu items with pricing and modifiers
• Carts: Shopping cart management and pricing
• Cart Items: Add, update, and remove items from carts
• Customers: Basic customer information for orders
• Payments: Payment processing through Stripe
• Discounts: Discount codes and promotions

​

Request/Response Format

​

Request Format

// POST request example
fetch('/api/v1/locations/downtown-pizza/carts', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    marketplaceId: 'downtown-pizza',
    currentCartId: ''
  })
});

​

Response Format

// Success response
{
  "id": "cart_123",
  "items": [...],
  "subtotal": 2500,
  "tax": 200,
  "total": 2700
}

// Error response
{
  "error": "validation_error",
  "message": "Invalid location ID",
  "details": {
    "field": "locationId",
    "code": "invalid_format"
  }
}

​

HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Merchant subscription required
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

​

Rate Limiting

• Limit: 200 requests per 10 minutes per IP address
• Headers:
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: When the rate limit resets (Unix timestamp)
• Exceeded: Returns 429 status with retry information

​

Data Types

​

Common Types

• ID: MongoDB ObjectId string (e.g., "64a7b8c9d1e2f3a4b5c6d7e8")
• Slug: URL-friendly string (e.g., "downtown-pizza")
• Price: Integer in cents (e.g., 1299 for $12.99)
• Timestamp: ISO 8601 format (e.g., "2024-01-15T14:30:00Z")
• Time: 24-hour format (e.g., "14:30")

​

Location Identifiers

• ObjectId: 64a7b8c9d1e2f3a4b5c6d7e8
• Slug: downtown-pizza

​

Error Handling

​

Common Errors

// Invalid API key
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "status": 401
}

// Merchant subscription required
{
  "error": "forbidden",
  "message": "Merchant subscription required",
  "status": 403
}

// Rate limit exceeded
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "status": 429,
  "retryAfter": 60
}

​

Best Practices

1. Always check status codes: Don’t assume success
2. Handle rate limits: Implement exponential backoff
3. Parse error responses: Extract error details for debugging
4. Implement retries: For temporary failures (5xx errors)

​

Getting Started

​

1. Obtain API Key

​

2. Set Up Environment

# Environment variables
CRAVE_API_KEY=your_api_key_here
CRAVE_API_BASE_URL=https://api.cravejs.com
NEXT_PUBLIC_LOCATION_ID=your_location_id_here

Important: Always use the production API URL (https://api.cravejs.com) in your environment variables.

​

3. Make Your First Request

// Get location information
const response = await fetch('https://api.cravejs.com/api/v1/locations/your_location_id', {
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const location = await response.json();
console.log(location);

​

4. Explore the API

1. Get Location Info - Basic location details
2. Get Menu - Browse available products
3. Create Cart - Start a new order
4. Add Items - Add products to cart
5. Create Payment Intent - Process payment

​

Integration Examples

​

Basic Storefront Flow

// 1. Load location and menu
const [location, menu] = await Promise.all([
  fetchLocation(locationId),
  fetchMenu(locationId)
]);

// 2. Create cart when customer starts ordering
const cart = await createCart(locationId);

// 3. Add items to cart
await addItemToCart(locationId, cart.id, {
  productId: 'prod_123',
  quantity: 2,
  modifiers: []
});

// 4. Configure cart
await setCartDelivery(locationId, cart.id, deliveryAddress);
await setCartTip(locationId, cart.id, tipAmount);

// 5. Process payment
const paymentIntent = await createPaymentIntent(locationId, cart.id);
// Handle payment with Stripe...

​

Error Handling Example

async function safeApiCall(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`${error.error}: ${error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

​

Available Endpoints

​

Cart Management

• POST /locations/{locationId}/carts - Create a new cart
• GET /locations/{locationId}/carts/{cartId} - Get cart details
• DELETE /locations/{locationId}/carts/{cartId} - Delete a cart
• PUT /locations/{locationId}/carts/{cartId}/validate-and-update - Validate and update order
• PUT /locations/{locationId}/carts/{cartId}/gratuity - Update gratuity

​

Cart Items

• POST /locations/{locationId}/carts/{cartId}/cart-item - Add item to cart
• PATCH /locations/{locationId}/carts/{cartId}/cart-item/{itemId}/quantity - Update cart item quantity

​

Customer Authentication

• POST /login-customer - Login or register customer
• POST /verify-otp - Verify OTP
• GET /customer - Get customer details
• DELETE /customer/logout - Logout customer

​

Customer Data

• GET /customer/saved-payments - Get customer saved payments
• DELETE /customer/saved-payments/{paymentId} - Delete saved payment method
• GET /orders - Get customer orders (placeholder implementation)
• GET /addresses - Get customer addresses (placeholder implementation)

Note: Customer authentication and data endpoints are implemented but may require additional configuration for production deployment. The /orders and /addresses endpoints currently return placeholder responses while full functionality is under development.

​

Location & Menu

• GET /locations/{locationSlugOrId} - Get location basic info
• GET /locations/{locationId}/menus - Get location menus
• GET /locations/{locationId}/time-intervals - Get order time intervals
• GET /locations/{locationId}/gratuity - Get gratuity configuration
• GET /locations/{locationId}/redirect - Redirect to storefront URL

​

Products

• GET /locations/{locationId}/products - Get products by location
• GET /locations/{locationId}/products/popular - Get popular products
• GET /locations/{locationId}/products/{productId} - Get product details

​

Discounts

• POST /locations/{locationId}/discounts/apply-discount - Apply discount code
• DELETE /locations/{locationId}/discounts/apply-discount - Remove discount code

​

Payments

• GET /stripe/payment-intent - Generate Stripe payment intent (requires locationId and cartId parameters)

​

Next Steps

• Core Concepts - Understand the data model
• Quick Start Guide - Build your first integration
• API Reference - Detailed endpoint documentation
• Integration Guides - Practical examples

​

Support

• Email: hello@craveup.com
• Documentation: This API reference
• Status: Check API status at status.craveup.com