Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/*.

Catering & Events API

Manage catering orders, corporate events, custom menus, and fulfillment operations.

Authentication Required

All endpoints require a valid Bearer token. See Authentication for details.

Overview

Attribute	Value
Base Path	/api/v1/catering
Authentication	Bearer Token
Required Roles	catering_staff, manager, restaurant_manager, finance, tenant_admin, platform_admin, system_admin, super_admin

Order Endpoints

List Catering Orders

Retrieve catering orders with filtering.

GET /api/v1/catering/orders

Query Parameters

Parameter	Type	Description
location_id	uuid	Filter by location
status	string	Filter by order status
event_date	date	Filter by event date
customer_id	uuid	Filter by customer
min_total	number	Minimum order total
page	integer	Page number
limit	integer	Results per page

Response

{
  "data": [
    {
      "id": "cat_001",
      "order_number": "C-2026-0042",
      "customer": {
        "id": "cust_abc",
        "name": "Acme Corp",
        "contact_name": "John Smith",
        "email": "john@acme.com"
      },
      "event_date": "2026-02-15T12:00:00Z",
      "event_type": "corporate_lunch",
      "guest_count": 50,
      "status": "confirmed",
      "subtotal": 1250.00,
      "tax": 112.50,
      "total": 1362.50,
      "delivery_address": "123 Business Park Dr",
      "created_at": "2026-01-20T10:00:00Z"
    }
  ]
}

Order Status Values

Status	Description
inquiry	Initial inquiry received
quoted	Quote sent to customer
confirmed	Customer confirmed order
in_preparation	Kitchen preparing order
ready	Ready for delivery/pickup
in_transit	Out for delivery
delivered	Order delivered
completed	Event completed
cancelled	Order cancelled

---

Create Catering Order

Create a new catering order.

POST /api/v1/catering/orders

Request Body

{
  "location_id": "loc_123",
  "customer_id": "cust_abc",
  "event_type": "corporate_lunch",
  "event_date": "2026-02-15T12:00:00Z",
  "guest_count": 50,
  "items": [
    {
      "menu_item_id": "cat_item_001",
      "quantity": 50,
      "per_person": true,
      "special_instructions": "Vegetarian option for 10"
    },
    {
      "menu_item_id": "cat_item_002",
      "quantity": 5,
      "per_person": false
    }
  ],
  "delivery": {
    "type": "delivery",
    "address": "123 Business Park Dr, Suite 100",
    "contact_name": "Reception",
    "contact_phone": "+1234567890",
    "setup_required": true,
    "setup_time": "2026-02-15T11:30:00Z"
  },
  "special_requests": "Need extra napkins and plates",
  "dietary_notes": "10 vegetarian, 5 gluten-free"
}

---

Get Catering Order

Retrieve full order details.

GET /api/v1/catering/orders/{order_id}

Response

{
  "id": "cat_001",
  "order_number": "C-2026-0042",
  "customer": {...},
  "event_date": "2026-02-15T12:00:00Z",
  "event_type": "corporate_lunch",
  "guest_count": 50,
  "status": "confirmed",
  "items": [
    {
      "id": "item_001",
      "name": "Grilled Chicken Lunch Box",
      "quantity": 50,
      "unit_price": 18.00,
      "total": 900.00
    },
    {
      "id": "item_002",
      "name": "Beverage Station (serves 25)",
      "quantity": 2,
      "unit_price": 75.00,
      "total": 150.00
    }
  ],
  "subtotal": 1250.00,
  "service_fee": 125.00,
  "delivery_fee": 50.00,
  "tax": 112.50,
  "total": 1537.50,
  "deposit_amount": 500.00,
  "deposit_paid": true,
  "balance_due": 1037.50,
  "delivery": {
    "type": "delivery",
    "address": "123 Business Park Dr, Suite 100",
    "setup_required": true,
    "setup_time": "2026-02-15T11:30:00Z"
  },
  "timeline": [
    {"status": "inquiry", "timestamp": "2026-01-15T10:00:00Z"},
    {"status": "quoted", "timestamp": "2026-01-15T14:00:00Z"},
    {"status": "confirmed", "timestamp": "2026-01-16T09:00:00Z"}
  ]
}

---

Update Order Status

Progress order through fulfillment stages.

PATCH /api/v1/catering/orders/{order_id}/status

Request Body

{
  "status": "in_preparation",
  "notes": "Kitchen started prep at 8 AM"
}

---

Event Types

List Event Types

GET /api/v1/catering/event-types

Response

{
  "data": [
    {
      "id": "corporate_lunch",
      "name": "Corporate Lunch",
      "min_guests": 10,
      "max_guests": 500,
      "lead_time_hours": 48,
      "setup_included": true
    },
    {
      "id": "wedding",
      "name": "Wedding Reception",
      "min_guests": 50,
      "max_guests": 300,
      "lead_time_hours": 168,
      "setup_included": true,
      "requires_consultation": true
    },
    {
      "id": "birthday",
      "name": "Birthday Party",
      "min_guests": 10,
      "max_guests": 100,
      "lead_time_hours": 24
    }
  ]
}

---

Catering Menus

List Catering Menus

GET /api/v1/catering/menus

Response

{
  "data": [
    {
      "id": "menu_corporate",
      "name": "Corporate Catering Menu",
      "description": "Professional lunch and meeting options",
      "categories": [
        {
          "id": "boxed_lunches",
          "name": "Boxed Lunches",
          "items": [
            {
              "id": "cat_item_001",
              "name": "Grilled Chicken Box",
              "description": "Grilled chicken, salad, roll, cookie",
              "price": 18.00,
              "per_person": true,
              "min_quantity": 10,
              "dietary_flags": ["gluten-free-available"]
            }
          ]
        }
      ],
      "packages": [
        {
          "id": "pkg_001",
          "name": "Executive Lunch Package",
          "description": "Complete lunch service for corporate meetings",
          "price_per_person": 35.00,
          "min_guests": 15,
          "includes": ["entree", "2 sides", "beverages", "dessert", "setup"]
        }
      ]
    }
  ]
}

---

Quotes

Quote Validity

Quotes have a configurable validity period (shown in the valid_until field). Expired quotes cannot be accepted and a new quote must be generated with current pricing.

Generate Quote

Generate a price quote for a potential order.

POST /api/v1/catering/quotes

Request Body

{
  "event_type": "corporate_lunch",
  "guest_count": 50,
  "event_date": "2026-02-15",
  "items": [
    {"menu_item_id": "cat_item_001", "quantity": 50}
  ],
  "delivery_required": true,
  "setup_required": true
}

Response

{
  "quote_id": "quote_abc123",
  "valid_until": "2026-01-31T23:59:59Z",
  "items_subtotal": 900.00,
  "service_fee": 90.00,
  "delivery_fee": 50.00,
  "setup_fee": 100.00,
  "tax": 99.40,
  "total": 1239.40,
  "deposit_required": 400.00,
  "deposit_due_date": "2026-02-08"
}

Accept Quote

Convert quote to confirmed order.

POST /api/v1/catering/quotes/{quote_id}/accept

---

Fulfillment

Get Fulfillment Schedule

View orders scheduled for fulfillment.

GET /api/v1/catering/fulfillment

Query Parameters

Parameter	Type	Description
date	date	Fulfillment date
location_id	uuid	Kitchen location

Response

{
  "date": "2026-02-15",
  "orders": [
    {
      "order_id": "cat_001",
      "event_time": "12:00",
      "guest_count": 50,
      "prep_start": "08:00",
      "delivery_depart": "11:00",
      "items_summary": "50 boxed lunches, 2 beverage stations",
      "status": "in_preparation"
    }
  ],
  "capacity": {
    "total_guests_today": 150,
    "max_capacity": 200,
    "utilization_percent": 75
  }
}

---

Webhooks

Event	Description
catering.order_created	New catering order
catering.order_confirmed	Order confirmed
catering.prep_started	Kitchen prep started
catering.ready	Order ready
catering.delivered	Order delivered
catering.completed	Event completed

---

Error Responses

Status	Code	Description
400	insufficient_lead_time	Not enough advance notice
400	below_minimum_guests	Guest count below minimum
400	exceeds_capacity	Date at capacity
404	order_not_found	Catering order not found
409	quote_expired	Quote no longer valid

---

Related Documentation

• Catering Guide - Manager guide
• Orders API - Regular orders
• Menus API - Menu management