Authenticated API

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

Delivery API

Manage delivery orders and integrate with third-party platforms.

Authentication Required

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

Overview

The Delivery API supports:

Feature	Description
Platform Integration	DoorDash, Uber Eats, Grubhub
In-House Delivery	Own driver management
Order Routing	Automatic platform assignment
Real-Time Tracking	Driver location updates
Menu Sync	Keep platform menus updated

---

Supported Platforms

Platform	Status	Features
DoorDash	Active	Orders, Menu Sync, Dispatch
Uber Eats	Active	Orders, Menu Sync
Grubhub	Active	Orders, Menu Sync
In-House	Active	Full driver management

---

List Delivery Orders

Request

GET /api/v1/delivery/orders?
  location_id=loc-xyz789&
  status=pending,preparing&
  platform=doordash
Authorization: Bearer {access_token}

Response

{
  "orders": [
    {
      "id": "del-12345",
      "order_id": "order-67890",
      "platform": "doordash",
      "platform_order_id": "dd-abc123",
      "status": "preparing",
      "customer": {
        "name": "John Smith",
        "phone": "555-123-4567",
        "address": {
          "line1": "123 Main St",
          "line2": "Apt 4B",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102"
        },
        "delivery_instructions": "Ring bell, leave at door"
      },
      "items": [
        {"name": "Classic Burger", "quantity": 2},
        {"name": "Fries", "quantity": 2}
      ],
      "subtotal": 35.98,
      "delivery_fee": 4.99,
      "platform_fee": 5.40,
      "total": 46.37,
      "estimated_pickup": "2026-01-18T12:30:00Z",
      "estimated_delivery": "2026-01-18T12:55:00Z",
      "created_at": "2026-01-18T12:00:00Z"
    }
  ]
}

---

Get Delivery Order

Request

GET /api/v1/delivery/orders/{delivery_id}
Authorization: Bearer {access_token}

Response

{
  "id": "del-12345",
  "status": "out_for_delivery",
  "driver": {
    "name": "Mike D.",
    "phone": "555-987-6543",
    "vehicle": "Silver Honda Civic",
    "location": {
      "lat": 37.7749,
      "lng": -122.4194,
      "updated_at": "2026-01-18T12:45:00Z"
    }
  },
  "tracking_url": "https://track.doordash.com/abc123",
  "timeline": [
    {"status": "received", "timestamp": "2026-01-18T12:00:00Z"},
    {"status": "confirmed", "timestamp": "2026-01-18T12:01:00Z"},
    {"status": "preparing", "timestamp": "2026-01-18T12:05:00Z"},
    {"status": "ready", "timestamp": "2026-01-18T12:25:00Z"},
    {"status": "picked_up", "timestamp": "2026-01-18T12:32:00Z"},
    {"status": "out_for_delivery", "timestamp": "2026-01-18T12:32:00Z"}
  ]
}

---

Update Order Status

Request

PUT /api/v1/delivery/orders/{delivery_id}/status
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "status": "ready",
  "estimated_pickup_minutes": 5
}

Status Values

Status	Description
received	Order received from platform
confirmed	Order accepted
preparing	Kitchen preparing
ready	Ready for pickup
picked_up	Driver collected
out_for_delivery	En route to customer
delivered	Successfully delivered
cancelled	Order cancelled

---

Accept/Reject Order

Accept Order

POST /api/v1/delivery/orders/{delivery_id}/accept
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "prep_time_minutes": 20
}

Reject Order

POST /api/v1/delivery/orders/{delivery_id}/reject
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reason": "item_unavailable",
  "unavailable_items": ["item-wings"]
}

Rejection Reasons

Platform Response Windows

Third-party platforms (DoorDash, Uber Eats, Grubhub) require accept/reject responses within their configured timeout windows (typically 3-5 minutes). If auto_accept is disabled, ensure staff are monitoring incoming delivery orders to avoid automatic cancellations by the platform.

Reason	Description
item_unavailable	Menu item out of stock
too_busy	Kitchen overwhelmed
closing_soon	Near closing time
address_issue	Delivery address problem
other	Other reason (provide notes)

---

In-House Delivery

Create Delivery

POST /api/v1/delivery/dispatch
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "order_id": "order-12345",
  "driver_id": "driver-001",
  "estimated_delivery_minutes": 30
}

Assign Driver

PUT /api/v1/delivery/orders/{delivery_id}/driver
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "driver_id": "driver-002"
}

List Drivers

GET /api/v1/delivery/drivers?
  location_id=loc-xyz789&
  status=available
Authorization: Bearer {access_token}

{
  "drivers": [
    {
      "id": "driver-001",
      "name": "Alex Johnson",
      "phone": "555-111-2222",
      "status": "available",
      "current_deliveries": 0,
      "vehicle": "2020 Toyota Prius"
    }
  ]
}

---

Menu Sync

Sync Menu to Platform

POST /api/v1/delivery/menu-sync
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "menu_id": "menu-main",
  "platforms": ["doordash", "ubereats"],
  "options": {
    "sync_prices": true,
    "sync_availability": true,
    "sync_images": true
  }
}

Response

{
  "sync_id": "sync-001",
  "status": "completed",
  "results": [
    {
      "platform": "doordash",
      "items_synced": 45,
      "errors": []
    },
    {
      "platform": "ubereats",
      "items_synced": 45,
      "errors": []
    }
  ]
}

Update Item Availability

PUT /api/v1/delivery/platforms/availability
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "item_id": "item-wings",
  "available": false,
  "platforms": ["doordash", "ubereats", "grubhub"]
}

---

Platform Settings

Get Platform Configuration

GET /api/v1/delivery/platforms/{platform}?location_id=loc-xyz789
Authorization: Bearer {access_token}

Response

{
  "platform": "doordash",
  "enabled": true,
  "store_id": "dd-store-123",
  "auto_accept": true,
  "prep_time_default": 20,
  "busy_prep_time": 35,
  "menu_sync_enabled": true,
  "last_sync": "2026-01-18T06:00:00Z"
}

Update Platform Settings

PUT /api/v1/delivery/platforms/{platform}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "auto_accept": false,
  "prep_time_default": 25,
  "pause_orders": false
}

---

Pause/Resume Orders

Pause Platform

POST /api/v1/delivery/platforms/{platform}/pause
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "location_id": "loc-xyz789",
  "reason": "Kitchen overwhelmed",
  "duration_minutes": 30
}

Resume Platform

POST /api/v1/delivery/platforms/{platform}/resume
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "location_id": "loc-xyz789"
}

---

Analytics

Delivery Metrics

GET /api/v1/delivery/analytics?
  location_id=loc-xyz789&
  start_date=2026-01-01&
  end_date=2026-01-18
Authorization: Bearer {access_token}

Response

{
  "summary": {
    "total_orders": 450,
    "total_revenue": 15750.00,
    "platform_fees": 2362.50,
    "net_revenue": 13387.50,
    "avg_delivery_time_minutes": 28
  },
  "by_platform": [
    {"platform": "doordash", "orders": 200, "revenue": 7000.00},
    {"platform": "ubereats", "orders": 150, "revenue": 5250.00},
    {"platform": "grubhub", "orders": 100, "revenue": 3500.00}
  ]
}

---

Webhooks

Delivery Events

Event	Description
delivery.order.received	New order from platform
delivery.order.updated	Order status changed
delivery.driver.assigned	Driver assigned
delivery.completed	Delivery completed
delivery.cancelled	Order cancelled

---

Error Responses

Platform Error (502)

{
  "error": {
    "code": "PLATFORM_ERROR",
    "message": "Failed to communicate with DoorDash",
    "platform": "doordash"
  }
}

---

Related Documentation

• Orders API - Order management
• Delivery Platforms Guide - Setup guide