# Seating

Seating (or the display and selection of individual seats) is key to the ticketing process. As such, an understanding
of the concepts and APIs in this area is required before creating a client application for ticketing.

## Seat selection

A seat selection user interface (UI) must render the [seat layout](#seat-layouts) data, combined with the current
[seat availability](#seat-availability) to display an up-to-date indication of the available seats.

The seat selection UI should also enforce any relevant [seat selection rules](#seat-selection-rules) to ensure optimal allocation
of available seats.

NOTE
For access to React-based seat selection UI reference code, talk to your local Vista representative.

## Seat layouts

A seat layout describes a physical auditorium, including its areas and seats. A seat layout is considered largely
static and will be heavily cached by the Digital API. Each *site* has a number of *screens* (theatres/auditoriums),
and each *screen* may have multiple *seat layouts* (configurations).

Each showtime is linked to a particular *seat layout*. To load a particular seat layout, use the [GetSeatLayout](/openapi/digital-platform/openapi/seating/ocapiseatlayout_getseatlayout/) endpoint with the relevant `seatLayoutId` for the showtime.

## Area categories

Each *seat layout* includes a number of *areas*. Each area belongs to an *area category* that determines
which ticket(s) can be purchased for seats within the area.

IMPORTANT
The client UI must restrict ticket and/or seat selection based on the area categories and quantities of the previously
selected tickets/seats.

## Seat allocation

Seat allocation may be required or disabled for a particular showtime, depending its `isAllocatedSeating` property. When `isAllocatedSeating` is `false`:

- The seat selection process must be skipped by the client.
- Patrons will not be able to select seats. It will be 'first-come, first-served' at the cinema.
- Patrons will not be able to access seat availability information.


A showtime with allocated seating may automatically allocate seats during ticket selection, note:

- If auto-allocation is disabled, the patron MUST select seats manually.
- If auto-allocation fails due to limitations in the allocation algorithm, the patron MUST select seats manually.
- If auto-allocation is successful, the patron may skip seat selection. However, it is typical for a seat selection UI to be presented to allow the patron to review or change their allocated seats.


## Seat types

Vista supports a number of different seat types which behave slightly differently. Typically the seat selection UI components handle the rules around these.

| Type | Description |
|  --- | --- |
| Normal | A regular single seat. |
| Sofa | Sofa seats are grouped together to represent any multi-person seating arrangement. Often it is enforced that a patron purchases tickets for the entire sofa rather than a part of it. |
| Wheelchair | These represent locations reserved in the theatre for those in a wheelchair. |
| Companion seat | These represent seats placed adjacent to wheelchair seats and reserved for companions of the wheelchair occupant. Often it is enforced that these can only be selected when the linked wheelchair seat is also selected. |


NOTE
Sofa seat groups consist of one `SofaLeft` and one `SofaRight` seat, and may include one or more `SofaMiddle` seats between the left and right seats.

## Seat selection rules

The rules around how and when seats can be reserved is highly configurable in Vista applications, including rules such as:

- Patrons can't leave a single seat gap between selected seats.
- Patrons can't leave a single seat gap between selected seats and unavailable seats.
- Patrons can't leave a single seat gap between a seat and the aisle.
- Patrons can't select a companion seat without also selecting a wheelchair seat.
- Patrons must select all seats within a sofa seat group.


NOTE
This logic is enforced in the UI layer only. The Digital API will not enforce any rules around seat types or locations.

## Seat availability

Seat availability represents the current `Sold`/`Available` status of each seat in a showtime. Use the
[GetSeatAvailabilityForShowtime](/openapi/digital-platform/openapi/seating/ocapiseatavailability_getseatavailabilityforshowtime/)
endpoint to load the current seat availability information for a particular showtime.

Seat availability is considered 'live data' and is only micro-cached for a few seconds.

### Seat previews

When displaying a non-interactive preview of seat availability for a showtime, use the `?preview=true` request parameter
of the [GetSeatAvailabilityForShowtime](/openapi/digital-platform/openapi/seating/ocapiseatavailability_getseatavailabilityforshowtime/) endpoint to load a more heavily cached version of the data.

IMPORTANT
Omit the `?preview=true` request parameter when loading seat availability for an interactive seat selection UI to ensure that
the most up-to-date seat availability is displayed for seat selection.

### Existing orders

For existing ticket orders, use the [GetSeatAvailabilityForOrder](/openapi/digital-platform/openapi/seating/ocapiseatavailability_getseatavailabilityfororder/) endpoint to load the current seat availability of a showtime
in the context of the particular order. This endpoint:

- Returns the `Available` status for any seats that have already been reserved for the order.
- Returns the `House` status for any seats that have been blocked due to social distance seating rules.


## Completed orders

For completed orders, to enable patrons to swap their seats within a showtime, refer to the [seat
swaps](/digital-platform/completed-orders/seat-swaps) page.