Reservations

Book tables, manage the lifecycle (pending → confirmed → arrived → seated → completed), and let Tablezio score no-show risk for every booking.

Check availability

GET

/v1/reservations/availability Scope: reservations:read

Returns the bookable time slots for a date, computed from the restaurant’s configured opening hours and real table capacity (existing reservations and a buffer between sittings are taken into account). Use it to power a booking widget: ask for a date, show the guest only the slots where a table for their party is free, then POST to create the reservation. A day the restaurant is closed returns closed:true with an empty slots array.

Query parameters

datestring (YYYY-MM-DD)Optional

Required. The day to check.

party_sizeintegerOptional

Guests to seat. Filters slots to tables that fit. Default 2.

fromstring (HH:MM)Optional

Override the window start (else opening hours).

tostring (HH:MM)Optional

Override the window end (else closing time).

slot_intervalintegerOptional

Minutes between slots (else the restaurant’s slot duration, default 30).

Request

curl 'https://api.tablezio.com/v1/reservations/availability?date=2026-06-12&party_size=4' \
  -H 'X-API-Key: tbz_…'

Response

application/json

{
  "object": "reservation_availability",
  "date": "2026-06-12",
  "party_size": 4,
  "slot_interval_minutes": 30,
  "open": true,
  "closed": false,
  "slots": [
    { "time": "13:00", "available": true,  "remaining_capacity": 6, "total_reservations": 1 },
    { "time": "13:30", "available": true,  "remaining_capacity": 4, "total_reservations": 2 },
    { "time": "14:00", "available": false, "remaining_capacity": 0, "total_reservations": 5 }
  ]
}

List reservations

GET

/v1/reservations Scope: reservations:read

Returns reservations for the restaurant. Filter by status, exact date (YYYY-MM-DD) or a date range with date.gte / date.lte.

Query parameters

limitintegerOptional

Page size, default 10, max 100.

starting_afterstringOptional

Cursor.

ending_beforestringOptional

Cursor (backwards).

statusstringOptional

Filter by status.

pendingconfirmedarrivedseatedcompletedcancelledno_show

datestring (YYYY-MM-DD)Optional

Restrict to a single day.

date.gteinteger (unix)Optional

Lower bound of reservation date.

date.lteinteger (unix)Optional

Upper bound of reservation date.

expandstring[]Optional

table.

Request

curl 'https://api.tablezio.com/v1/reservations?date=2026-06-12' -H 'X-API-Key: tbz_…'

Response

application/json

{ "object": "list", "data": [ /* reservation */ ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/reservations" }

Retrieve a reservation

GET

/v1/reservations/{id} Scope: reservations:read

Fetch a single reservation.

Path parameters

idstringRequired

Reservation ID (rsv_…).

Query parameters

expandstring[]Optional

table.

Request

curl https://api.tablezio.com/v1/reservations/rsv_… -H 'X-API-Key: tbz_…'

Response

application/json

{
  "id": "rsv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "reservation",
  "created": 1716730000,
  "updated": 1716730000,
  "guest": { "name": "Lucia", "email": "[email protected]", "phone": null },
  "customer": null,
  "party_size": 4,
  "date": "2026-06-12",
  "time": "20:30",
  "duration_minutes": 90,
  "table": null,
  "status": "confirmed",
  "arrived_at": null,
  "seated_at": null,
  "completed_at": null,
  "source": "api",
  "notes": null,
  "special_requests": "Anniversary dinner",
  "tags": [],
  "no_show_risk": 5
}

Create a reservation

POST

/v1/reservations Scope: reservations:write

Books a table. We compute a no-show risk score based on the guest history and reservation properties.

Body parameters

guest_namestringRequired

Display name shown on the floor plan.

party_sizeintegerRequired

Number of guests, >= 1.

datestring (YYYY-MM-DD)Required

Reservation date.

timestring (HH:MM)Required

Reservation time, 24-hour clock.

guest_emailstringOptional

Used for confirmation emails when configured.

guest_phonestringOptional

Used for SMS confirmations.

duration_minutesintegerOptional

Expected dinner length. Defaults to 90.

tablestringOptional

Specific table id; omit to let auto-assign pick.

notesstringOptional

Internal staff notes.

special_requestsstringOptional

Guest-visible requests (allergies, occasion).

tagsstring[]Optional

Free-form tags for filtering.

sourcestringOptional

Where the booking came from (api, widget, walk-in…).

Request

curl -X POST https://api.tablezio.com/v1/reservations \
  -H 'X-API-Key: tbz_…' \
  -H 'Idempotency-Key: rsv_lucia_2026-06-12_20:30' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_name": "Lucia",
    "guest_email": "[email protected]",
    "party_size": 4,
    "date": "2026-06-12",
    "time": "20:30",
    "special_requests": "Anniversary dinner"
  }'

Response

application/json

{
  "id": "rsv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "reservation",
  "created": 1716730000,
  "updated": 1716730000,
  "guest": { "name": "Lucia", "email": "[email protected]", "phone": null },
  "customer": null,
  "party_size": 4,
  "date": "2026-06-12",
  "time": "20:30",
  "duration_minutes": 90,
  "table": null,
  "status": "confirmed",
  "arrived_at": null,
  "seated_at": null,
  "completed_at": null,
  "source": "api",
  "notes": null,
  "special_requests": "Anniversary dinner",
  "tags": [],
  "no_show_risk": 5
}

Update a reservation

PATCH

/v1/reservations/{id} Scope: reservations:write

Edit guest details, party size, time slot, or table. Status transitions live on the /status route below.

Path parameters

idstringRequired

Reservation ID.

Body parameters

*anyOptional

Any field accepted on create.

Request

curl -X PATCH https://api.tablezio.com/v1/reservations/rsv_… \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{ "party_size": 5 }'

Response

application/json

{
  "id": "rsv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "reservation",
  "created": 1716730000,
  "updated": 1716730000,
  "guest": { "name": "Lucia", "email": "[email protected]", "phone": null },
  "customer": null,
  "party_size": 4,
  "date": "2026-06-12",
  "time": "20:30",
  "duration_minutes": 90,
  "table": null,
  "status": "confirmed",
  "arrived_at": null,
  "seated_at": null,
  "completed_at": null,
  "source": "api",
  "notes": null,
  "special_requests": "Anniversary dinner",
  "tags": [],
  "no_show_risk": 5
}

Update reservation status

PATCH

/v1/reservations/{id}/status Scope: reservations:write

Move the reservation through its lifecycle. Emits reservation.updated, reservation.cancelled, or reservation.no_show.

Path parameters

idstringRequired

Reservation ID.

Body parameters

statusstringRequired

Target status.

pendingconfirmedarrivedseatedcompletedcancelledno_show

Request

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

Response

application/json

{
  "id": "rsv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "reservation",
  "created": 1716730000,
  "updated": 1716730000,
  "guest": { "name": "Lucia", "email": "[email protected]", "phone": null },
  "customer": null,
  "party_size": 4,
  "date": "2026-06-12",
  "time": "20:30",
  "duration_minutes": 90,
  "table": null,
  "status": "confirmed",
  "arrived_at": null,
  "seated_at": null,
  "completed_at": null,
  "source": "api",
  "notes": null,
  "special_requests": "Anniversary dinner",
  "tags": [],
  "no_show_risk": 5
}

Cancel a reservation

POST

/v1/reservations/{id}/cancel Scope: reservations:write

Shortcut for setting status to cancelled. Emits reservation.cancelled.

Path parameters

idstringRequired

Reservation ID.

Request

curl -X POST https://api.tablezio.com/v1/reservations/rsv_…/cancel -H 'X-API-Key: tbz_…'

Response

application/json

{
  "id": "rsv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "reservation",
  "created": 1716730000,
  "updated": 1716730000,
  "guest": { "name": "Lucia", "email": "[email protected]", "phone": null },
  "customer": null,
  "party_size": 4,
  "date": "2026-06-12",
  "time": "20:30",
  "duration_minutes": 90,
  "table": null,
  "status": "confirmed",
  "arrived_at": null,
  "seated_at": null,
  "completed_at": null,
  "source": "api",
  "notes": null,
  "special_requests": "Anniversary dinner",
  "tags": [],
  "no_show_risk": 5
}