How to calculate capacity-based availability

In this article

Before you start

• The user can manage reservations and use automatic reservations internally: `reservation:manage` plus `reservation-automatic:use`. Reading the occurrence detail requires `reservation:view` or `reservation:manage`.
• The service occurrence belongs to Harbor Soho, is a future `service` occurrence, has `booking_mode=automatic` and has `acceptance_state=open`.
• The occurrence or its event has both `layout_id` and `optimization_config_id`.
• The selected layout contains tables and may contain configured table combinations.
• The optimisation runtime is configured and reachable because availability depends on the external `/available` call.
• For public booking, the occurrence is public, not ended, not deleted and belongs to the organisation and location in the public URL.

Instructions

1. 1.

   Open the service occurrence

   From Harbor Soho reservations, open the future automatic service occurrence you want to book. Do not use the capacity calculation on manual, waiting-list, completed or past occurrences.

2. 2.

   Start a new reservation

   Choose New reservation and enter the party size. The internal availability query runs only when the organisation, location, occurrence and party size are all known.

3. 3.

   Set table requirements if needed

   Leave tables open when the optimiser should choose the best resource. If the operator selects tables, assign mode sends fixed `table_ids`, required mode sends `restricted_table_ids`, and preferred mode sends `preferred_table_ids`.

4. 4.

   Review the available slots

   Check the returned times, duration, table names, resource type, score and optimisation metrics. Cancelled and waitlist reservations do not consume capacity; fixed or optimiser-applied assignments lock existing reservations to their resources.

5. 5.

   Handle no availability

   An empty `slots` response is a valid no-availability result. Internally, the modal can offer the waiting-list or manual fallback; in public booking, guests cannot select a time if the optimiser cannot return availability.

6. 6.

   Continue from a selected slot

   After an operator or guest chooses a slot, the later reservation creation step uses that choice. Availability is read-only and does not hold capacity by itself.

7. 7.

   Use the public booking surface

   Guests use the Harbor Soho public booking page to reach the time step. When public table preferences are disabled, preference fields are ignored before the same capacity-backed calculation runs.

Validations and limits

• Availability endpoints require `POST` and valid JSON.
• `occurrence_id` is required unless the path endpoint supplies it from `occurrenceId`.
• `party_size` must be greater than 0.
• The occurrence must belong to the route location and its event must have `kind=service`.
• Missing `layout_id` blocks the calculation; missing `optimization_config_id` leaves the runtime in an invalid state.
• The internal workflow is blocked without `reservation-automatic:use`.
• The public occurrence must be visible publicly and must not have ended.
• If `optimization.BaseURL` is empty or `/available` fails, slots cannot be generated.
• Returned slots are a snapshot; another reservation can consume the capacity before confirmation.

Expected result

The operator or guest sees capacity-aware booking options for the current service snapshot. No reservation, waitlist entry or table assignment is created until the later confirmation flow runs.