Create an optimised reservation

In this article

Before you start

• An authenticated `/api/app` session is active with Harbor Demo Group and Harbor Soho selected.
• The occurrence belongs to Harbor Soho, is a `service` occurrence, uses `booking_mode` automatic and has `acceptance_state` open.
• The occurrence is not for a past service day in the event or location timezone.
• The service resolves to a layout and optimisation configuration for the current location.
• The operator can manage reservations for the location and automatic reservation use is enabled.
• The optimiser is available, and the operator has the customer full name and phone number ready.

Instructions

1. 1.

   Open the service occurrence

   Open the reservations calendar or go directly to the Harbor Soho occurrence detail. Confirm it is the intended automatic service and that the page shows `New reservation`.

2. 2.

   Start New reservation

   Select `New reservation`. When the optimiser is online, the app opens the optimised reservation modal for the current occurrence. If it is offline, use the manual fallback offered by the app.

3. 3.

   Set guests and table conditions

   Enter the party size. Keep table mode indifferent when any suitable table is acceptable; use preferred, required or assign only when the customer needs specific tables, then choose at least one table.

4. 4.

   Choose an optimiser slot

   Review the calculated slots and choose a start time using the score, risk, saturation, preference indicators and table names. If a slot is double-turn eligible, explain the expected departure time before continuing.

5. 5.

   Enter customer details

   Enter the customer full name and phone number. This surface creates a new customer record first and does not show an existing-customer selector in the analysed flow.

6. 6.

   Confirm the booking

   Submit the reservation. The backend recalculates availability, accepts the booking only if the selected start time still matches a slot, creates the booked phone-channel reservation and refreshes the occurrence.

Validations and limits

• `New reservation` is available only for automatic, open service occurrences that are not past and belong to the current location.
• Party size must be greater than zero; the picker allows values from 1 to 999.
• A table selection is required when table mode is not indifferent.
• Customer name and customer phone are required before confirmation.
• The backend rejects non-service occurrences, occurrences from another location, missing layouts and missing optimisation configurations.
• The selected `starts_at` must still exist in the slots recalculated during booking; otherwise the save fails with a conflict.
• Fixed table assignments are persisted only when the booking sends `table_ids`; preferred or restricted tables are not automatically saved as assignment rows.
• The waitlist fallback creates a waitlist reservation through `/reservations`, not a confirmed booking through `/optimization/book`.
• If post-book optimisation returns a warning after creation, the reservation remains and the occurrence should be reviewed manually.

Expected result

A new customer and booked reservation are created for Harbor Soho, the occurrence is refreshed, optimisation cache is marked stale for the changed occurrence, and a post-book optimisation run is started.