API reference

Reservations API

Reservations are the tables a venue holds for a guest, whether staff typed them in or they came from a confirmed booking request.

To follow requests that still need a decision, use Bookings.

List reservations

GET/api-v1-reservations

Scope: reservations.read
Plan: Sansflow Premium
Paginated: cursor

Returns reservations newest first by reserved_at (the reservation time, not when it was made).

Query parameters

Name	Type	Required	Description
`from`	string	Optional	Earliest reserved_at, inclusive. ISO 8601 with offset, or YYYY-MM-DD.A bare date means 00:00 UTC that day, so pass a full timestamp with +07:00 to cut at local midnight.
`to`	string	Optional	Latest reserved_at, inclusive. ISO 8601 with offset, or YYYY-MM-DD.A bare date means 00:00 UTC that day, so pass a full timestamp with +07:00 to cut at local midnight.
`location_id`	uuid	Optional	Only this outlet. A key pinned to one outlet is always scoped to it; another outlet’s id is 403.
`status`	string	Optional	One of booked, seated, completed, cancelled, no_show.
`cursor`	string	Optional	The next_cursor from the previous page. Opaque; send it back unchanged.
`limit`	integer	Optional	Rows per page.Default 50. At least 1; values above 100 are capped at 100.

Response fields (200)

Name	Type	Description
`data[].code`	string	The reservation code.
`data[].reserved_at`	timestamp	When the party is expected.
`data[].duration_minutes`	integer	How long the table is held.
`data[].status`	string	booked, seated, completed, cancelled or no_show.
`data[].table`	string \| null	The table’s name.

Errors

Every error answers { "error": { "code", "message", "request_id" } }. Branch on code; see Errors for retrying.

HTTP	Code	When
400	`validation_failed`	A query parameter did not parse; the message names it. Also returned when from/to span more than 400 days.
401	`invalid_key`	The Authorization header is missing, malformed, or the key is revoked or inactive.
402	`payment_required`	The business’s plan does not include API access (Sansflow Premium). The key itself is fine.
403	`insufficient_scope`	The key does not carry the scope this endpoint needs, or it is pinned to a different outlet.
429	`rate_limited`	Over the key’s per-minute limit (60 for sf_test_, 300 for sf_live_). Wait the seconds in Retry-After.
500	`internal_error`	Something failed on our side. Quote the request_id when you report it.

Request

curl -G "https://ewpuclvmnygoddunkyrb.supabase.co/functions/v1/api-v1-reservations" \
  -H "Authorization: Bearer $SANSFLOW_API_KEY" \
  --data-urlencode "from=2026-11-08T00:00:00+07:00" \
  --data-urlencode "to=2026-11-08T23:59:59+07:00"

const url = new URL("https://ewpuclvmnygoddunkyrb.supabase.co/functions/v1/api-v1-reservations");
url.search = new URLSearchParams({
  "from": "2026-11-08T00:00:00+07:00",
  "to": "2026-11-08T23:59:59+07:00"
}).toString();

const res = await fetch(
  url,
  {
    headers: {
      Authorization: `Bearer ${process.env.SANSFLOW_API_KEY}`,
    },
  },
);
const json = await res.json();
if (!res.ok) throw new Error(`${json.error.code} (${json.error.request_id})`);
console.log(json);

import os
import requests

res = requests.get(
    "https://ewpuclvmnygoddunkyrb.supabase.co/functions/v1/api-v1-reservations",
    headers={
        "Authorization": f"Bearer {os.environ['SANSFLOW_API_KEY']}",
    },
    params={
        "from": "2026-11-08T00:00:00+07:00",
        "to": "2026-11-08T23:59:59+07:00",
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']} ({data['error']['request_id']})")
print(data)

Response200 OK

{
  "data": [
    {
      "id": "d2f6b8a4-1c3e-4b5d-9a87-6e0f2c4b8d35",
      "code": "R-261108-003",
      "customer_id": "c4e8a2f1-6b9d-4e3a-8f72-1d5c9b0a3e24",
      "customer_name": "Budi",
      "customer_phone": "+6281300000000",
      "customer_email": null,
      "party_size": 4,
      "reserved_at": "2026-11-08T12:00:00+00:00",
      "duration_minutes": 90,
      "status": "booked",
      "notes": null,
      "location_id": "3f6c2a1e-8b4d-4c2a-9e51-7a0d2b6c9f10",
      "table": "T12",
      "created_at": "2026-11-06T03:12:45+00:00",
      "updated_at": "2026-11-06T03:20:10+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "5d0c7e2a-91f4-4b3e-a8c6-0f2e4b6d8a1c"
}

Example values. Run replays this response here; nothing is sent.

Base URL, keys and conventions: API reference overview.Events for this resource: Webhooks reference.

Stuck? Quote the request_id from the response and write toSansflow support.Checked against API v1 on 8 Nov 2026.