Reservations Overview

Overview

The Reservations API lets your application manage the lifecycle of a dining reservation at a SpotOn merchant location — from seating a guest through to completion.. Before defining the workflow, let's establish the core concepts:

• Location: A single SpotOn merchant venue, identified by its SpotOn location ID in the form BL-XXXX-XXXX-XXXX. Every request is scoped to a location.
• Reservation: A booking for a party at a location, identified by an external reservation ID that you assign. You own this identifier and use it on every follow-up request for that reservation.

A reservation moves through a small set of states. You seat a party, optionally adjust it (reseat to a different table, change the party size), and finally complete or cancel it. The sections below walk through each step.

---

Activating a Location

Before you can create reservations for a location, you must activate the location. Activation registers the location for reservation traffic and links it to your partner-assigned restaurant identifier, so later requests can resolve to the right venue.

Activate Location

Activate reservations for a location using the merchant's SpotOn location ID.

API Resource: POST - Activate Location

Note: Activation is the onboarding entry point — you must do it once per location before sending reservations. Each location maps to exactly one external_restaurant_id. Calling activate again for the same location with a different external_restaurant_id is rejected — contact SpotOn support if the mapping needs to change.

---

Managing Reservations

Seat Reservation

Create a reservation and mark the party as seated.

API Resource: POST - Seat Reservation

Required Body Parameters

• external_restaurant_id — your restaurant identifier for the location.
• external_reservation_id — the unique identifier you assign to this reservation.
• party_size — number of guests.
• scheduled_time — the reservation date and time (UTC).
• customer — guest contact information (first name and phone are required).

You can optionally include table names, server names, free-form notes, and party flags (for example, VIP or wheelchair) in the request body. The response returns the reservation with its current status.

Adjust Seated Reservation

Adjust a reservation once a party is seated using the API resources below:

• POST - Reseat Reservation — move the party to a different table.
• POST - Change Party Size — update the number of guests.
• POST - Unseat Reservation — return the party to an unseated state.

Each resource targets an existing reservation using the external_reservation_id provided in the request path.

Cancel Reservation

Cancel a reservation by external_reservation_id. (Note: This is a terminal action)

API Resource: POST - Cancel Reservation

---

Reservation Status

Every reservation response includes a status describing where the reservation is in its lifecycle:

• Seated — the party has been seated.
• Unseated — the reservation exists but the party is not currently seated.
• Cancelled — the reservation has been cancelled.
• Completed — the reservation has finished.

---

Reservation Ticket Webhooks

When you seat a reservation via the Reservation CAPI, SpotOn opens a POS ticket against it and delivers a webhook event (category EVENT_CATEGORY_FOH) every time the ticket changes — items added, courses progressed, payments recorded, ticket closed. Each event is a full snapshot of the ticket at that moment, so partners can stay in lockstep with the POS without polling. A typical seated party can generate dozens of events over the course of a meal; subscribe and react as they arrive.

---

Errors

Reservation resources use standard HTTP status codes. The codes you should handle are:

Error responses share a common shape with a numeric code, a message, and an optional details array.

---

What's Next

• Reservations API Reference — full request and response schemas for every operation.
• SpotOn OAuth – Integration Guide — obtain a token with the reservation:all:write scope.