API reference · Reservations

Book a table

POST/v1/reservations

Creates a booking. It appears in every Billzova app (POS, Android, dashboard) for the restaurant to confirm.

Scope reservations:write
30 / minute (and 3 per customer phone per day)
Needs Idempotency-Key

Body

dateYYYY-MM-DDrequired: From availability.
timeHH:MMrequired: An available slot's time.
peopleintegerrequired: Party size.
customer.name / phone / emailobjectrequired: Name, 10-digit Indian mobile, optional email.
occasionstring ≤ 60: e.g. Birthday.
notesstring ≤ 300: Seating preference, allergies…

Request

curl https://api.billzova.com/v1/reservations \
  -H "Authorization: Bearer $BILLZOVA_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: book-7c1a" \
  -d '{"date":"2026-10-24","time":"20:00","people":4,"customer":{"name":"Priya","phone":"9812345670"},"occasion":"Birthday"}'

const booking = await fetch('https://api.billzova.com/v1/reservations', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.BILLZOVA_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ date: '2026-10-24', time: '20:00', people: 4, customer: { name: 'Priya', phone: '9812345670' }, occasion: 'Birthday' }),
}).then((r) => r.json());

Response

201 · application/json

{
  "id": "r-91…", "object": "reservation", "test": false, "status": "PENDING",
  "date": "2026-10-24", "time": "20:00", "until": "21:30", "people": 4,
  "customer": { "name": "Priya", "phone": "9812345670", "email": null },
  "occasion": "Birthday", "price": { "amount": 20000, "currency": "INR", "display": "₹200", "status": "DUE" },
  "trackingUrl": "https://billzova.com/track/Lq…"
}

Good to know

Statuses: PENDING → CONFIRMED → SEATED, or REJECTED / CANCELLED / NO_SHOW.

Errors

Code	HTTP	Meaning
IDEMPOTENCY_KEY_REQUIRED	400	Send an `Idempotency-Key` header with every create.
SLOT_UNAVAILABLE	409	That time is not available — `available` lists the free times.
PARTY_TOO_LARGE	422	More guests than an online booking allows.
BOOKINGS_OFF	403	Table booking is switched off.
RESTAURANT_UNAVAILABLE	403	The restaurant cannot take orders or bookings (subscription or account).
VALIDATION_FAILED	422	The body is invalid — `field` says where.
RATE_LIMITED	429	Too many requests — wait for `Retry-After` seconds.