API Endpoints

This document describes the OneTablet API endpoints that your platform calls to submit orders, request cancellations, and send delivery updates.

Overview

Your platform acts as an API client calling OneTablet's endpoints.

Endpoint Configuration

OneTablet provides your API base URL and authentication credentials during integration setup.

Authentication

Include authentication in your API requests as configured during integration:

curl -X POST "{ONETABLET_API_URL}/orders" \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{...}'

See Authentication for details.

Submit Order

Submit a new order when a customer places an order on your platform.

Endpoint: POST /orders

Request Body

{
  "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,
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+15551234567"
  },
  "categories": [
    {
      "merchant_supplied_id": "cat-appetizers",
      "name": "Appetizers",
      "items": [
        {
          "merchant_supplied_id": "item-wings-001",
          "name": "Buffalo Wings",
          "quantity": 1,
          "price": 1299,
          "consumer_name": "John Doe",
          "special_instructions": "Extra crispy",
          "extras": []
        }
      ]
    }
  ],
  "order_special_instructions": "Ring doorbell",
  "subtotal": 2500,
  "tax": 225,
  "merchant_tip_amount": 500,
  "is_pickup": false,
  "estimated_pickup_time": "2024-01-15T18:30:00Z",
  "fulfillment_type": "dx_delivery",
  "delivery_address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip_code": "10001",
    "lat": "40.7128",
    "lng": "-74.0060",
    "address_instructions": "Apt 4B, buzz 42"
  },
  "delivery_fee": 299,
  "experience": "YOUR_PLATFORM",
  "commission_type": "regular",
  "is_tax_remitted_by_platform": false,
  "tax_amount_remitted_by_platform": 0,
  "tax_transaction_id": "tax-txn-123",
  "applied_discounts": []
}

See Order Schema for the complete order structure.

Response

200 OK - Order received successfully

Example

curl -X POST "{ONETABLET_API_URL}/orders" \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d @order.json

Cancel Order

Request cancellation of an order.

Endpoint: POST /orders/{order_id}/cancel

Path Parameters

Parameter	Type	Description
`order_id`	string	Your order ID (`id` from the original order)

Request Body

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

Fields

Field	Type	Required	Description
`store.merchant_supplied_id`	string	Yes	Store ID
`client_order_id`	string	Yes	OneTablet's internal order ID (received in confirmation webhook)
`reason`	string	Yes	Cancellation reason

Response

200 OK - Cancellation request received

Example

curl -X POST "{ONETABLET_API_URL}/orders/your-order-uuid/cancel" \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "store": {
      "merchant_supplied_id": "store-123"
    },
    "client_order_id": "onetablet-12345",
    "reason": "Customer requested cancellation"
  }'

Update Delivery Status

Send delivery status updates when your courier's status changes (required if you manage delivery).

Endpoint: POST /orders/{order_id}/delivery-status

Path Parameters

Parameter	Type	Description
`order_id`	string	Your order ID

Request Body

{
  "client_order_id": "onetablet-order-id",
  "dasher_status": "arriving_at_store",
  "dasher": {
    "phone_number": "+15559876543",
    "first_name": "Mike",
    "last_name": "Driver",
    "vehicle": {
      "color": "Blue",
      "make": "Toyota",
      "model": "Camry"
    }
  }
}

Fields

Field	Type	Required	Description
`client_order_id`	string	Yes	OneTablet's internal order ID
`dasher_status`	string	Yes	Current delivery status (see below)
`dasher.phone_number`	string	Yes	Courier's phone number
`dasher.first_name`	string	No	Courier's first name
`dasher.last_name`	string	No	Courier's last name
`dasher.vehicle`	object	No	Vehicle information

Delivery Status Values

Status	Description
`dasher_confirmed`	Courier has been assigned and confirmed
`arriving_at_store`	Courier is en route to the restaurant
`arrived_at_store`	Courier has arrived at the restaurant
`dasher_out_for_delivery`	Courier has picked up order, en route to customer
`dropoff`	Delivery completed

Status Flow

dasher_confirmed → arriving_at_store → arrived_at_store → dasher_out_for_delivery → dropoff

Response

200 OK - Status update received

Example

curl -X POST "{ONETABLET_API_URL}/orders/your-order-uuid/delivery-status" \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "onetablet-12345",
    "dasher_status": "arriving_at_store",
    "dasher": {
      "phone_number": "+15559876543",
      "first_name": "Mike"
    }
  }'

Order Flow

After you submit an order:

You call POST /orders to submit the order
OneTablet routes the order to the restaurant's tablet/POS
Restaurant confirms or rejects the order
OneTablet calls your webhook with the confirmation (see Webhooks)
Restaurant marks order ready when prepared
OneTablet calls your webhook with the ready notification
(If you manage delivery) You call POST /orders/{id}/delivery-status to update courier status

┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
│  Your Platform  │        │   OneTablet     │        │   Restaurant    │
└────────┬────────┘        └────────┬────────┘        └────────┬────────┘
         │                          │                          │
         │  1. POST /orders         │                          │
         │─────────────────────────►│                          │
         │                          │  2. Route to tablet      │
         │                          │─────────────────────────►│
         │                          │                          │
         │                          │  3. Restaurant confirms  │
         │                          │◄─────────────────────────│
         │  4. Confirmation webhook │                          │
         │◄─────────────────────────│                          │
         │                          │                          │
         │                          │  5. Order ready          │
         │                          │◄─────────────────────────│
         │  6. Ready webhook        │                          │
         │◄─────────────────────────│                          │
         │                          │                          │
         │  7. POST /orders/{id}/   │                          │
         │     delivery-status      │                          │
         │─────────────────────────►│  (displayed on tablet)   │

Error Responses

Status	Description
`200 OK`	Request processed successfully
`400 Bad Request`	Invalid request data
`401 Unauthorized`	Authentication failed
`404 Not Found`	Order not found
`409 Conflict`	Action conflicts with current order state
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error (retry recommended)

Error Response Body

{
  "error": "Error Type",
  "message": "Human-readable error description"
}

Best Practices

Idempotency

Include unique identifiers so duplicate requests can be detected:

Use unique id for each order
The store_order_cart_id should be consistent if the same cart is resubmitted

Timeouts

Set a reasonable timeout (30 seconds recommended)
If OneTablet doesn't respond in time, retry

Retry Logic

Implement exponential backoff for failed requests:

const delays = [1000, 5000, 30000]; // 1s, 5s, 30s

async function callApiWithRetry(request) {
  for (let attempt = 0; attempt < delays.length; attempt++) {
    try {
      const response = await fetch(request.url, {
        method: request.method,
        headers: {
          'x-api-key': API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(request.body)
      });

      if (response.ok) return response;

      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }
    } catch (error) {
      if (attempt < delays.length - 1) {
        await sleep(delays[attempt]);
      } else {
        throw error; // All retries exhausted
      }
    }
  }
}

Logging

Log all API calls with:

Timestamp
Endpoint called
Order/reference ID
Response status
Any error messages

Testing

During integration, OneTablet provides:

Sandbox environment - Test API calls without affecting production
Test credentials - Sandbox authentication
Request logs - View API calls in a dashboard

Contact OneTablet technical support to set up your test environment.

Overview​

Authentication​

Submit Order​

Request Body​

Response​

Example​

Cancel Order​

Path Parameters​

Request Body​

Fields​

Response​

Example​

Update Delivery Status​

Path Parameters​

Request Body​

Fields​

Delivery Status Values​

Status Flow​

Response​

Example​

Order Flow​

Error Responses​

Error Response Body​

Best Practices​

Idempotency​

Timeouts​

Retry Logic​

Logging​

Testing​

Overview

Authentication

Submit Order

Request Body

Response

Example

Cancel Order

Path Parameters

Request Body

Fields

Response

Example

Update Delivery Status

Path Parameters

Request Body

Fields

Delivery Status Values

Status Flow

Response

Example

Order Flow

Error Responses

Error Response Body

Best Practices

Idempotency

Timeouts

Retry Logic

Logging

Testing