Reservations Overview

Activate a location and manage the full lifecycle of a reservation.

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.
  • Table: A dining table configured in the merchant's point of sale (POS) for a location. Each table has a display name that you reference when seating or reseating a party.

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.


Listing Tables

Retrieve the dining tables configured for a location so you can assign a party to a specific table when you seat or reseat it.

API Resource: GET - List Tables

Path Parameter

  • location_id — the SpotOn location ID (BL-XXXX-XXXX-XXXX).

Response

The response contains a tables array. Each table has:

  • id — the POS table identifier.
  • name — the table's display name.

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).
  • table_names — table names assigned to the reservation.
  • server_names — server names assigned to the reservation.

You can optionally include 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:

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:

CodeMeaning
200Success.
400The request is invalid (malformed or missing required fields).
401The request is unauthorized (missing or invalid token).
403The request is forbidden (the token lacks the required scope).
404The location or reservation was not found.
409The request conflicts with the current state of the reservation.
500An unexpected error occurred.

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


What's Next


Did this page help you?