Saltar al contenido

Orders

Orders

The Order resource represents a single check — dine-in, takeout or delivery. Orders move through a defined lifecycle (draft → placed → preparing → ready → served → completed) and emit webhooks on every transition.

List orders

GET /v1/orders Scope: orders:read

Returns orders for the authenticated restaurant, newest first. Combine cursor pagination, status / type filters and date ranges to slice the history.

Query parameters

limitintegerOptional

Page size, default 10, max 100.

starting_afterstringOptional

Cursor from a previous response. Returns items older than this cursor.

ending_beforestringOptional

Cursor from a previous response. Returns items newer than this cursor.

statusstringOptional

Filter by status.

draftplacedpreparingreadyservedcompletedcancelled
typestringOptional

Filter by order type.

dine_intakeoutdelivery
tablestringOptional

Filter to a specific table id (tbl_…).

created.gteinteger (unix)Optional

Only return orders created at or after this timestamp.

created.lteinteger (unix)Optional

Only return orders created at or before this timestamp.

expandstring[]Optional

Inline references. Supported: table, server, items.menu_item.

Request

curl 'https://api.tablezio.com/v1/orders?limit=2&status=placed' \
  -H 'X-API-Key: tbz_…'

Response

application/json
{
  "object": "list",
  "data": [ /* order objects */ ],
  "has_more": true,
  "next_cursor": "v1:5a1b2c…:1716657480000",
  "previous_cursor": null,
  "url": "/v1/orders"
}

Retrieve an order

GET /v1/orders/{id} Scope: orders:read

Fetch a single order by its prefixed ID.

Path parameters

idstringRequired

The order ID (e.g. ord_507f1f77bcf86cd799439011).

Query parameters

expandstring[]Optional

Inline references: table, server, items.menu_item.

Request

curl 'https://api.tablezio.com/v1/orders/ord_507f1f77bcf86cd799439011?expand[]=items.menu_item' \
  -H 'X-API-Key: tbz_…'

Response

application/json
{
  "id": "ord_507f1f77bcf86cd799439011",
  "object": "order",
  "created": 1716730000,
  "updated": 1716730000,
  "order_number": "ORD-042",
  "type": "takeout",
  "status": "draft",
  "source": "pos",
  "table": null,
  "server": null,
  "customer": {
    "name": "Carlos",
    "phone": "+34 600 000 000",
    "email": null
  },
  "delivery_address": null,
  "estimated_time_minutes": null,
  "items": [
    {
      "object": "order_item",
      "index": 0,
      "menu_item": "mi_5a1b2c3d4e5f6a7b8c9d0e1f",
      "name": "Classic burger",
      "quantity": 2,
      "unit_price": 1200,
      "modifiers": [],
      "notes": null,
      "status": "pending",
      "station": "kitchen",
      "sent_to_kitchen_at": null,
      "ready_at": null
    }
  ],
  "subtotal": 2400,
  "tax_amount": 0,
  "discount_amount": 0,
  "tip_amount": 0,
  "delivery_fee": 0,
  "total": 2400,
  "currency": "usd",
  "notes": null,
  "placed_at": null,
  "completed_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "is_self_service": false,
  "is_virtual_table": false,
  "virtual_table_label": null,
  "livemode": true
}

Create an order

POST /v1/orders Scope: orders:write

Creates a new order. Menu item IDs are resolved against the catalogue — names and prices come from your menu, not the request. Pass Idempotency-Key to make the call safely retryable.

Body parameters

typestringRequired

Order channel.

dine_intakeoutdelivery
itemsarrayRequired

One or more line items: { menu_item, quantity, modifiers?, notes? }.

tablestringOptional

Table ID for dine_in orders.

customer_namestringOptional

Display name on the ticket.

customer_phonestringOptional

Used for SMS notifications when configured.

customer_emailstringOptional

Used for emailed receipts when configured.

delivery_addressstringOptional

Required for delivery orders if dispatching couriers.

notesstringOptional

Free-form kitchen notes.

Items honour the latest menu prices server-side; pricing sent by clients is ignored.

Request

curl -X POST https://api.tablezio.com/v1/orders \
  -H 'X-API-Key: tbz_…' \
  -H 'Idempotency-Key: order_2026-05-26_carlos_1' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "takeout",
    "customer_name": "Carlos",
    "items": [
      { "menu_item": "mi_5a1b2c3d4e5f6a7b8c9d0e1f", "quantity": 2 }
    ]
  }'

Response

application/json
{
  "id": "ord_507f1f77bcf86cd799439011",
  "object": "order",
  "created": 1716730000,
  "updated": 1716730000,
  "order_number": "ORD-042",
  "type": "takeout",
  "status": "draft",
  "source": "pos",
  "table": null,
  "server": null,
  "customer": {
    "name": "Carlos",
    "phone": "+34 600 000 000",
    "email": null
  },
  "delivery_address": null,
  "estimated_time_minutes": null,
  "items": [
    {
      "object": "order_item",
      "index": 0,
      "menu_item": "mi_5a1b2c3d4e5f6a7b8c9d0e1f",
      "name": "Classic burger",
      "quantity": 2,
      "unit_price": 1200,
      "modifiers": [],
      "notes": null,
      "status": "pending",
      "station": "kitchen",
      "sent_to_kitchen_at": null,
      "ready_at": null
    }
  ],
  "subtotal": 2400,
  "tax_amount": 0,
  "discount_amount": 0,
  "tip_amount": 0,
  "delivery_fee": 0,
  "total": 2400,
  "currency": "usd",
  "notes": null,
  "placed_at": null,
  "completed_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "is_self_service": false,
  "is_virtual_table": false,
  "virtual_table_label": null,
  "livemode": true
}

Update order status

PATCH /v1/orders/{id} Scope: orders:write

Transition the order to the next lifecycle status. Emits the matching webhook (order.updated, order.completed, order.cancelled).

Path parameters

idstringRequired

The order ID.

Body parameters

statusstringRequired

Target status.

placedpreparingreadyservedcompletedcancelled
cancel_reasonstringOptional

Required when transitioning to cancelled. Shown on receipts and audit logs.

Request

curl -X PATCH https://api.tablezio.com/v1/orders/ord_… \
  -H 'X-API-Key: tbz_…' \
  -H 'Content-Type: application/json' \
  -d '{ "status": "placed" }'

Response

application/json
{
  "id": "ord_507f1f77bcf86cd799439011",
  "object": "order",
  "created": 1716730000,
  "updated": 1716730000,
  "order_number": "ORD-042",
  "type": "takeout",
  "status": "draft",
  "source": "pos",
  "table": null,
  "server": null,
  "customer": {
    "name": "Carlos",
    "phone": "+34 600 000 000",
    "email": null
  },
  "delivery_address": null,
  "estimated_time_minutes": null,
  "items": [
    {
      "object": "order_item",
      "index": 0,
      "menu_item": "mi_5a1b2c3d4e5f6a7b8c9d0e1f",
      "name": "Classic burger",
      "quantity": 2,
      "unit_price": 1200,
      "modifiers": [],
      "notes": null,
      "status": "pending",
      "station": "kitchen",
      "sent_to_kitchen_at": null,
      "ready_at": null
    }
  ],
  "subtotal": 2400,
  "tax_amount": 0,
  "discount_amount": 0,
  "tip_amount": 0,
  "delivery_fee": 0,
  "total": 2400,
  "currency": "usd",
  "notes": null,
  "placed_at": null,
  "completed_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "is_self_service": false,
  "is_virtual_table": false,
  "virtual_table_label": null,
  "livemode": true
}

Cancel an order

POST /v1/orders/{id}/cancel Scope: orders:write

Convenience shortcut for PATCH …/orders/{id} with status: "cancelled". Idempotent.

Path parameters

idstringRequired

The order ID.

Body parameters

cancel_reasonstringOptional

Optional reason — recorded on the order and on the resulting webhook.

Request

curl -X POST https://api.tablezio.com/v1/orders/ord_…/cancel \
  -H 'X-API-Key: tbz_…' \
  -H 'Content-Type: application/json' \
  -d '{ "cancel_reason": "Customer changed mind" }'

Response

application/json
{
  "id": "ord_507f1f77bcf86cd799439011",
  "object": "order",
  "created": 1716730000,
  "updated": 1716730000,
  "order_number": "ORD-042",
  "type": "takeout",
  "status": "draft",
  "source": "pos",
  "table": null,
  "server": null,
  "customer": {
    "name": "Carlos",
    "phone": "+34 600 000 000",
    "email": null
  },
  "delivery_address": null,
  "estimated_time_minutes": null,
  "items": [
    {
      "object": "order_item",
      "index": 0,
      "menu_item": "mi_5a1b2c3d4e5f6a7b8c9d0e1f",
      "name": "Classic burger",
      "quantity": 2,
      "unit_price": 1200,
      "modifiers": [],
      "notes": null,
      "status": "pending",
      "station": "kitchen",
      "sent_to_kitchen_at": null,
      "ready_at": null
    }
  ],
  "subtotal": 2400,
  "tax_amount": 0,
  "discount_amount": 0,
  "tip_amount": 0,
  "delivery_fee": 0,
  "total": 2400,
  "currency": "usd",
  "notes": null,
  "placed_at": null,
  "completed_at": null,
  "cancelled_at": null,
  "cancel_reason": null,
  "is_self_service": false,
  "is_virtual_table": false,
  "virtual_table_label": null,
  "livemode": true
}