> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cravejs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understanding the fundamental concepts of the Crave Storefront API

## Overview

The Crave Storefront API is designed around several core concepts that work together to enable online ordering experiences. Understanding these concepts will help you build effective storefronts.

## Core Entities

### Locations

**Locations** represent individual restaurant locations with their own menus, hours, and settings.

* **Location ID**: Can be either a MongoDB ObjectId (`64a7b8c9d1e2f3a4b5c6d7e8`) or a slug (`downtown-pizza`)
* **Multi-location support**: Each location operates independently
* **Geographic data**: Includes address, coordinates, and delivery radius
* **Operating hours**: Day-specific hours with timezone support
* **Fulfillment methods**: Delivery, pickup, dine-in, table service

```javascript theme={null}
// Example: Get location information
const location = await fetch(`/api/v1/locations/downtown-pizza`, {
  headers: { 'X-API-Key': 'your_api_key' }
});

// Location contains:
// - Basic info (name, address, contact)
// - Operating hours and timezone
// - Fulfillment methods available
// - Delivery radius and fees
// - Ordering capabilities
```

### Products & Menus

**Products** are the items customers can order, organized into **categories** within **menus**.

* **Hierarchical structure**: Menu → Categories → Products
* **Pricing**: Stored in cents (e.g., \$12.99 = 1299)
* **Availability**: Real-time availability checking
* **Modifiers**: Customization options (size, toppings, etc.)
* **Time-based filtering**: Products can be available at specific times

```javascript theme={null}
// Example: Get menu with products
const menu = await fetch(`/api/v1/locations/downtown-pizza/menus`, {
  headers: { 'X-API-Key': 'your_api_key' }
});

// Structure:
// menu.categories[] → category.products[] → product.modifiers[]
```

### Carts

**Carts** hold customer selections before checkout and handle all pricing calculations.

* **Session-based**: Each cart has a unique ID
* **Auto-calculation**: Subtotal, tax, tips, and delivery fees
* **Validation**: Ensures items are still available
* **Configuration**: Delivery address, table number, order time
* **Persistence**: Carts exist until explicitly deleted

```javascript theme={null}
// Example: Cart lifecycle
const cart = await fetch(`/api/v1/locations/downtown-pizza/carts`, {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body: JSON.stringify({
    marketplaceId: 'downtown-pizza',
    currentCartId: ''
  })
});

// Cart automatically calculates:
// - Subtotal (sum of all items)
// - Tax (based on location tax rates)
// - Delivery fee (if applicable)
// - Total (subtotal + tax + tip + fees)
```

### Orders

**Orders** are created automatically when payments succeed (not directly via API).

* **Webhook-based creation**: Created by Crave backend after payment
* **Immutable**: Cannot be modified once created
* **Merchant-managed**: Fulfillment handled by merchant dashboard
* **Status tracking**: Merchant updates status through their dashboard

## API Patterns

### Authentication

All API requests require authentication via API key:

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

### Location-Scoped Operations

All operations are scoped to a specific location:

```javascript theme={null}
// 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
```

### Error Handling

The API returns consistent error responses:

```javascript theme={null}
// Error response format:
{
  "error": "validation_error",
  "message": "Invalid location ID",
  "details": {
    "field": "locationId",
    "code": "invalid_format"
  }
}

// Common HTTP status codes:
// 200 - Success
// 400 - Bad Request (validation errors)
// 401 - Unauthorized (invalid API key)
// 403 - Forbidden (merchant subscription required)
// 404 - Not Found
// 429 - Rate limited
// 500 - Internal server error
```

### Rate Limiting

* **Limit**: 200 requests per 10 minutes per IP address
* **Headers**: `X-RateLimit-Remaining`, `X-RateLimit-Reset`
* **Exceeded**: Returns 429 with retry information

## Data Types

### Common Fields

Most entities include these common fields:

* **id**: Unique identifier (MongoDB ObjectId)
* **createdAt**: ISO timestamp when created
* **updatedAt**: ISO timestamp when last modified
* **isActive**: Boolean indicating if entity is active

### Price Format

All prices are stored as integers in cents:

```javascript theme={null}
// $12.99 is stored as 1299
const price = 1299;
const displayPrice = (price / 100).toFixed(2); // "12.99"
```

### Time Format

* **Times**: 24-hour format strings ("14:30")
* **Dates**: ISO 8601 timestamps ("2024-01-15T14:30:00Z")
* **Timezones**: Location-specific timezone handling

## Typical Integration Flow

Here's how a typical storefront integration works:

```javascript theme={null}
// 1. Load location information
const location = await fetchLocation(locationId);

// 2. Load menu and products
const menu = await fetchMenu(locationId);

// 3. Start an ordering session (creates or resumes a cart)
const { cartId } = await startOrderingSession(locationId, {
  fulfillmentMethod: 'pickup',
});

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

// 5. Configure cart (delivery, tip, etc.)
await setCartDelivery(locationId, cartId, deliveryAddress);
await setCartTip(locationId, cartId, tipAmount);

// 6. Validate cart before checkout
await validateCart(locationId, cartId);

// 7. Create payment intent
const paymentIntent = await createPaymentIntent(locationId, cartId);

// 8. Process payment with Stripe
// 9. Order is created automatically via webhook
```

## Best Practices

### Performance

* **Cache location data**: Changes infrequently
* **Cache menu data**: Update every 5-10 minutes
* **Don't cache carts**: Always fetch fresh cart data
* **Batch API calls**: Use Promise.all for parallel requests

### Error Handling

* **Implement retry logic**: For temporary failures
* **Validate inputs**: Before making API calls
* **Handle rate limits**: Implement exponential backoff
* **Monitor errors**: Track and log API errors

### Security

* **Server-side API keys**: Never expose in client code
* **Environment variables**: Store keys securely
* **HTTPS only**: Always use secure connections
* **Input validation**: Sanitize all user inputs

### User Experience

* **Loading states**: Show loading during API calls
* **Error messages**: Provide clear, actionable error messages
* **Optimistic updates**: Update UI immediately when possible
* **Offline handling**: Handle network connectivity issues

## Limitations

### Storefront Scope

The Storefront API is designed for customer-facing operations only:

* ✅ **Available**: Menu browsing, cart management, payment processing
* ❌ **Not Available**: Order management, menu editing, analytics
* ❌ **Not Available**: Real-time order tracking, customer accounts

### Merchant Requirements

* **Active subscription**: Merchant must have active or trial subscription
* **Onboarding complete**: Merchant must complete setup process
* **Payment configured**: Stripe integration must be set up

### Technical Constraints

* **Location-scoped**: Cannot perform cross-location operations
* **No real-time updates**: Polling required for data changes
* **Webhook-based orders**: Cannot create orders directly via API
* **Rate limited**: 200 requests per 10 minutes per IP

## Next Steps

Now that you understand the core concepts, explore the specific API endpoints:

* [Location APIs](/api-reference/storefront-api/store/getLocationBasicInfo) - Get location information
* [Menu APIs](/api-reference/storefront-api/menu/getStoreMenus) - Browse menus and products
* [Cart APIs](/api-reference/storefront-api/cart/getCart) - Manage shopping carts
* [Sessions](/api-reference/storefront-api/sessions/startOrderingSession) - Create or resume carts
* [Payment APIs](/api-reference/storefront-api/payment/createPaymentIntent) - Process payments
* [Implementation Guide](/guides/build-custom-storefront) - End-to-end storefront walkthrough