# Seat swaps

Seat swaps allow patrons to change their seats after completing a ticket order.

Seats can only be swapped to available seats within the original showtime and area categories. To change showtimes or area
categories, patrons must [refund their order](/digital-platform/completed-orders/refunds) and create a new one.

## Seat swap flow

```mermaid
flowchart TB
    A(Check seat swap availability) --> B
    B(Check showtime availability) --> C
    C(Patron selects new seats) --> D
    D(Validate selected seats) --> E
    E(Complete seat swap)

    click A "#check-seat-swap-availability"
    click B "#check-showtime-availability"
    click C "#patron-selects-new-seats"
    click D "#validate-selected-seats"
    click E "#complete-seat-swap"
```

## Check seat swap availability

Use the [GetCompletedOrder](/openapi/digital-platform/openapi/completed-orders/ocapicompletedorders_getcompletedorder/)
endpoint to determine if seat swaps are currently available for a completed order.

Each showtime in the response includes a `seatSwapStatus` object with an `isAvailable` property.

- A `true` value indicates that seat swaps are available for the showtime.
- If `false`, the `unavailableReason` will indicate the reason that seat swaps are not available.


Refer to [seat swap unavailable scenarios](#seat-swap-unavailable-scenarios) for more
information.

```json
{
  "order": {
    "id": "string",
    "showtimes": [
      {
        "showtimeId": "string",
        "seatSwapStatus": {
          "isAvailable": true,
          "unavailableReason": "NotApplicable"
        }
      },
      {
        "showtimeId": "string",
        "seatSwapStatus": {
          "isAvailable": false,
          "unavailableReason": "ShowtimeEnded"
        }
      }
    ]
  }
}
```

NOTE
Some properties have been omitted from the code snippet above for brevity.

## Check showtime availability

Use the [GetShowtime](/openapi/digital-platform/openapi/showtimes/ocapishowtimes_getshowtime/) endpoint to check if
the showtime has sold out. The response includes an `isSoldOut` property. If `true`, the showtime has sold out and seat
swaps are no longer available.

The `showtime` also includes a `seatLayoutId`, which is used to load the seat layout via the
[GetSeatLayout](/openapi/digital-platform/openapi/seating/ocapiseatlayout_getseatlayout/) endpoint.

```json
{
  "showtime": {
    "id": "string",
    "isSoldOut": false,
    "seatLayoutId": "string"
  }
}
```

NOTE
Some properties have been omitted from the code snippet above for brevity.

## Patron selects new seats

Once seat swap availability has been confirmed, the patron can select their new seats.

Use the [GetSeatLayout](/openapi/digital-platform/openapi/seating/ocapiseatlayout_getseatlayout/) endpoint with the
`seatLayoutId` of the showtime to load the seat layout and use
[GetSeatAvailabilityForOrder](/openapi/digital-platform/openapi/seating/ocapiseatavailability_getseatavailabilityfororder/)
endpoint to load the current seat availability.

Patrons can only select seats that have an `Available` status and belong to the same area categories as their original seats.

For more information, refer to [seat selection](/digital-platform/seating#seat-selection).

## Validate selected seats

Validate the selected seats to ensure they meet any relevant [seat selection rules](/digital-platform/seating#seat-selection-rules).

NOTE
The [SwapSeats](/openapi/digital-platform/openapi/completed-orders/ocapicompletedorders_swapseats) endpoint ensures the
correct number of seats are selected and that they match the area categories of the original seats, but it doesn't
enforce rules like preventing single seat gaps.

## Complete seat swap

After the selected seats have been validated, use the
[SwapSeats](/openapi/digital-platform/openapi/completed-orders/ocapicompletedorders_swapseats) endpoint with the unique
identifiers of the new seats to complete the seat swap.

```json
{
  "seats": ["string"]
}
```

A `200` response indicates that the seat swap was successful and includes the updated completed order.

A `400` response indicates an error has occurred, commonly due to stale data (completed order, showtime, or seat
availability), or due to the selected seats not matching the area categories of the original seats.

See [seat swap unavailable scenarios](#seat-swap-unavailable-scenarios) for more information.

## Seat swap unavailable scenarios

Seat swaps may be unavailable for the following reasons:

- Seat swaps have not been enabled for the circuit.
- The showtime has unallocated seating.
- The showtime has ended.
- The showtime has sold out.
- The order does not include any seats for the showtime.
- The order includes package tickets for the showtime.
- The order includes an in-seat item delivery for the showtime.
- The order has not been completed. Use the
[SetShowtime](/openapi/digital-platform/openapi/showtimes/ocapiordershowtimes_setshowtime/) endpoint to change seats
for an in-progress order.
- The order has been refunded.
- The order is an unpaid booking.


The [SwapSeats](/openapi/digital-platform/openapi/completed-orders/ocapicompletedorders_swapseats) endpoint will return a
`400` response with an error for the scenarios above.

## Swapping showtimes

Seats can only be swapped to new seats within the original showtime. If patrons wish to change showtimes, they must
[refund their order](/digital-platform/completed-orders/refunds) and create a new one.

## Swapping area categories

Seats can only be swapped to new seats within the same area categories as the original seats. If patrons wish to change
area categories (i.e., upgrade or downgrade), they must [refund their order](/digital-platform/completed-orders/refunds) and create a new one.