Order Lifecycle

This document describes the complete lifecycle of an order from your platform through OneTablet to the restaurant.

Order Flow Overview

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Customer   │     │    Your      │     │  OneTablet   │
│   Orders on  │────►│  Platform    │────►│              │
│   Your App   │     │              │     │              │
└──────────────┘     └──────────────┘     └──────────────┘
                            │                    │
                     1. POST /orders        2. Route to
                                               restaurant
                            │                    │
                            │                    ▼
                            │              ┌──────────────┐
                            │              │  Restaurant  │
                            │              │    (POS)     │
                            │              └──────────────┘
                            │                    │
                            ▼                    │
                     3. Receive          ◄───────┘
                        confirmation            │
                            │                   │
                            ▼                   │
                     4. Receive          ◄──────┘
                        ready notification
                            │
                            ▼
                     5. Complete
                        fulfillment

Who Does What

Action	Your Platform	OneTablet
Display menu	✓ (receive from us)	✓ (push to you)
Collect customer order	✓
Send order to restaurant	✓ (POST /orders)	✓ (route to POS)
Accept/reject order		✓ (call your webhook)
Mark order ready		✓ (call your webhook)
Manage delivery	✓ (if your fleet)	✓ (if platform delivery)
86 items		✓ (call your webhook)
Pause store		✓ (call your webhook)

---

Order States

From Your Platform's Perspective

State	Description	Your Action
Submitted	You called POST /orders	Wait for confirmation webhook
Confirmed	Order accepted by restaurant	Notify customer, wait for ready
Rejected	Order declined by restaurant	Notify customer, process refund
Ready	Restaurant marked order ready	Dispatch delivery or notify customer
In Transit	Courier has picked up order	Track delivery progress
Completed	Order delivered/picked up	Order lifecycle complete
Cancelled	Order cancelled	Handle refund if needed

---

Step 1: Submit Order to OneTablet

When a customer places an order on your platform, call OneTablet's API:

POST /orders

{
  "id": "your-order-uuid",
  "store_order_cart_id": "cart-id",
  "delivery_short_code": "ABC123",
  "store": {
    "merchant_supplied_id": "store-123",
    "provider_type": "your_platform",
    "timezone": "America/New_York",
    "store_business": {
      "auto_release_enabled": true
    }
  },
  "consumer": {
    "id": 12345,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+15551234567"
  },
  "subtotal": 2500,
  "tax": 225,
  "is_pickup": false,
  "estimated_pickup_time": "2024-01-15T18:30:00Z",
  "categories": [...]
}

See API Endpoints for complete details.

---

Step 2: Receive Confirmation/Rejection (Webhook)

OneTablet calls your webhook endpoint with the order confirmation:

Order Accepted

// PATCH /orders/{order_id}
{
  "merchant_supplied_id": "restaurant-internal-id",
  "order_status": "success",
  "prep_time": "2024-01-15T18:30:00Z"
}

Your action: Update order status, notify customer with estimated ready time.

Order Rejected

// PATCH /orders/{order_id}
{
  "merchant_supplied_id": "restaurant-internal-id",
  "order_status": "fail",
  "failure_reason": "Store is currently closed"
}

Your action: Notify customer, process refund.

---

Step 3: Receive Ready Notification (Webhook)

When the restaurant marks the order ready, OneTablet calls your webhook endpoint:

// PATCH /orders/{order_id}/events/order_ready_for_pickup
{
  "merchant_supplied_id": "restaurant-internal-id"
}

Your action:

• For pickup: Notify customer order is ready
• For delivery: Dispatch courier or wait for platform delivery

---

Step 4: Delivery Updates (If Applicable)

If you manage delivery, call OneTablet's API to send status updates:

POST /orders/{order_id}/delivery-status

{
  "client_order_id": "onetablet-order-id",
  "dasher_status": "arriving_at_store",
  "dasher": {
    "first_name": "Mike",
    "phone_number": "+15559876543"
  }
}

Delivery Status Flow

dasher_confirmed → arriving_at_store → arrived_at_store → dasher_out_for_delivery → dropoff

Status	Description
dasher_confirmed	Courier assigned to order
arriving_at_store	Courier heading to restaurant
arrived_at_store	Courier at restaurant location
dasher_out_for_delivery	Courier picked up, en route to customer
dropoff	Delivery completed

---

Step 5: Order Cancellation

You Cancel an Order

Call OneTablet's API to request cancellation:

POST /orders/{order_id}/cancel

{
  "store": {
    "merchant_supplied_id": "store-123"
  },
  "client_order_id": "onetablet-order-id",
  "reason": "Customer requested cancellation"
}

Restaurant Cancels (Webhook to You)

OneTablet calls your webhook endpoint:

// PATCH /orders/{order_id}/cancellation
{
  "cancel_reason": "ITEM_OUT_OF_STOCK",
  "cancel_details": "Requested item no longer available"
}

Cancellation Reason Codes

Reason	Description
ITEM_OUT_OF_STOCK	Required item is unavailable
STORE_CLOSED	Store is no longer accepting orders
KITCHEN_BUSY	Kitchen capacity exceeded
OTHER	Other reason (see cancel_details)

---

Fulfillment Types

Orders have different fulfillment types:

Type	Description	Delivery Managed By
pickup	Customer picks up at restaurant	N/A
dx_delivery	Platform-managed delivery	Delivery platform
mx_fleet_delivery	Your delivery fleet	Your platform

---

Best Practices

Calling the API

1. Validate before sending - Ensure all required fields are populated
2. Use unique IDs - Each order should have a unique id
3. Handle failures - Retry with exponential backoff on failures

Handling Webhooks

1. Respond quickly - Return HTTP 200 within 30 seconds
2. Process asynchronously - Don't block on slow operations
3. Handle duplicates - Use order ID for idempotency

Status Management

1. Track internally - Maintain order state in your system
2. Log everything - Keep audit trail of all status changes
3. Support manual intervention - Allow staff to handle edge cases

---

Timing Guidelines

Action	Expected	Notes
Order confirmation	1-5 minutes	Depends on restaurant workflow
Ready notification	Varies	Based on prep time
Delivery pickup	5-15 minutes	After order ready
Delivery completion	15-45 minutes	Depends on distance