Reservations

Endpoint

POST https://api.getsuko.com/api/public/reservations

Headers

X-Restaurant-Key: sk_live_your_key
Content-Type: application/json

Request body

Field	Type	Required	Description
`guest_name`	string	Yes	Guest’s full name (max 100 chars)
`guest_phone`	string	Yes	Guest’s phone number
`party_size`	number	Yes	Number of guests (1–20)
`date`	string	Yes	Reservation date (`YYYY-MM-DD`)
`time`	string	Yes	Reservation time (`HH:MM`)
`guest_email`	string	No	Guest’s email — required for confirmation emails
`notes`	string	No	Special requests or notes

{
  "guest_name": "John Doe",
  "guest_phone": "+1234567890",
  "party_size": 4,
  "date": "2026-08-15",
  "time": "19:00",
  "guest_email": "john@example.com",
  "notes": "Window seat if possible"
}

Response

{
  "id": "uuid",
  "status": "pending",
  "message": "Reservation request received"
}

Example — fetch from a custom form

fetch('https://api.getsuko.com/api/public/reservations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Restaurant-Key': 'sk_live_your_key'
  },
  body: JSON.stringify({
    guest_name: 'John Doe',
    guest_phone: '+1234567890',
    party_size: 4,
    date: '2026-08-15',
    time: '19:00',
    notes: 'Window seat if possible'
  })
})
  .then(res => res.json())
  .then(data => console.log('Reservation ID:', data.id))

Example — curl

curl -X POST https://api.getsuko.com/api/public/reservations \
  -H "Content-Type: application/json" \
  -H "X-Restaurant-Key: sk_live_your_key" \
  -d '{
    "guest_name": "John Doe",
    "guest_phone": "+1234567890",
    "party_size": 4,
    "date": "2026-08-15",
    "time": "19:00"
  }'

CORS

This endpoint accepts cross-origin requests from any domain. Security is enforced via the X-Restaurant-Key header, not via CORS origin restrictions.

If you configure Allowed Domains in your restaurant settings, the Origin header of browser requests must match one of those domains.

Error responses

Status	Code	Description
`400`	`MISSING_FIELDS`	One or more required fields are missing — `missing_fields` array lists them
`400`	`VALIDATION`	A field failed format validation
`402`	`PAYMENT_REQUIRED`	Restaurant subscription inactive
`403`	`FORBIDDEN`	Invalid API key or origin domain not in allowed list
`409`	`NO_AVAILABILITY`	No seats available for the requested time
`429`	`RATE_LIMITED`	More than 5 requests from the same IP in one hour

Missing fields response example

{
  "error": "Missing required fields",
  "code": "MISSING_FIELDS",
  "missing_fields": ["guest_phone", "party_size"]
}

Public Data Next.js