# Bookings

The steps to making a booking are as follows:

1. **Check Availability:** Check availability and retrieve an availability ID.
2. **Booking Reservation:** Create a booking that reserves availability while you collect payment and customer details.
3. **Booking Confirmation:** Confirm the booking once payment is complete.

All routes in this page are public OCTO routes under `https://api.ventrata.com/octo`.

All booking routes are documented in the [Endpoints](#endpoints) section below.

## Endpoints

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings/{uuid}" method="patch" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings/{uuid}/confirm" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings/{uuid}/cancel" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings/{uuid}/extend" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings/{uuid}" method="get" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="<https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media>" path="/bookings" method="get" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

## After Confirmation: Fields to Use

When `POST /bookings/{uuid}/confirm` succeeds, prioritize these fields from the booking response:

* `booking.supplierReference`: Human-readable supplier reference. Give this to the guest and store it for customer support and billing reconciliation.
* `booking.voucher`: Use when `booking.deliveryMethods` contains `VOUCHER` (one ticket media object per booking).
* `booking.unitItems[].ticket`: Use when `booking.deliveryMethods` contains `TICKET` (one ticket media object per person/unit item).
* `booking.pricing.retail`: Retail amount in minor units that you must charge the guest for the booking.
* `booking.pricing.net`: Net amount in minor units that the supplier will invoice for the booking.

If `booking.deliveryMethods` contains both `VOUCHER` and `TICKET`, the reseller can choose what the guest prefers: one voucher for the booking, or one ticket per person.

The `booking.voucher` and `booking.unitItems[].ticket` objects have the same shape and provide guest-facing media in `deliveryOptions` (for example `PDF_URL`, `QRCODE`, and wallet links).

```json
{
  "supplierReference": "SUP-20260304-009871",
  "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
  "availabilityId": "2026-03-04T18:30:00+01:00",
  "deliveryMethods": ["VOUCHER", "TICKET"],
  "voucher": {
    "deliveryOptions": [
      {
        "deliveryFormat": "PDF_URL",
        "deliveryValue": "https://api.ventrata.com/octo/download/booking/89fe0192-ddcd-430a-b285-e1396a4725d2.pdf"
      }
    ]
  },
  "unitItems": [
    {
      "ticket": {
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "TKT-11111111"
          }
        ]
      }
    }
  ],
  "pricing": {
    "retail": 4600,
    "net": 3220,
    "currency": "USD",
    "currencyPrecision": 2
  }
}
```

For `GET /bookings`, include one primary filter from this set:

* `resellerReference`
* `supplierReference`
* `localDate`
* `localDateStart` + `localDateEnd`
* `availabilityId`
* `utcCreatedAtStart` + `utcCreatedAtEnd`
* `utcUpdatedAtStart` + `utcUpdatedAtEnd`
* `utcRedeemedAtStart` + `utcRedeemedAtEnd`
* `utcNoshowedAtStart` + `utcNoshowedAtEnd`
* `utcRebookedAtStart` + `utcRebookedAtEnd`
* `utcCancelledAtStart` + `utcCancelledAtEnd`
* `contactEmailAddress`
* `contactPhoneNumber`
* `contactLastName`

Supported status filter values are:

* `REDEEMED`
* `NO_SHOW`
* `ON_HOLD`
* `CANCELLED`
* `EXPIRED`
* `PENDING`
* `REJECTED`
* `REBOOKED`
* `QUOTE`
* `CONFIRMED`

Pagination notes:

* `page` and `perPage` are supported.
* `Octo-Total-Pages` response header is set when paginating.
* When `page` is omitted, the API may aggregate all pages internally and return one combined array.

Voucher/ticket delivery URLs are returned directly in `voucher.deliveryOptions[].deliveryValue` and `unitItems[].ticket.deliveryOptions[].deliveryValue`.