Booking

Reserving availability an making a booking

The steps to making a booking are as follows:

  1. Check Availability Check the availability in the previous section and retrieve an availability ID. **

  2. Booking Reservation Create a booking that reserves the availability while you collect payment and contact information from the customer.

  3. Booking Confirmation The final step, once payment has been taken and you want to finalise the booking.

post
Booking Reservation

https://api.ventrata.com/octo/bookings
The first step is to reserve the availability by creating the booking.
Request
Response
Request
Body Parameters
uuid
optional
string
A unique UUID to identify the booking. Setting this value acs like an idempotency key preventing you from double booking.
expirationMinutes
optional
integer
How many minutes to reserve the availability, otherwise defaults to the supplier default amount.
productId
required
integer
The product ID
optionId
required
string
The option ID
availabilityId
required
string
The availability ID
unitItems
required
array
An array of unit items
unitItems[].unitId
required
string
The unit item unit ID
unitItems[].uuid
optional
string
A unique UUID to identify the unit, same as the booking uuid except per unit.
Response
200: OK
{
"uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
"testMode": true,
"resellerReference": null,
"supplierReference": "X749G9",
"status": "ON_HOLD",
"utcExpiresAt": "2020-06-07T17:06:37Z",
"utcConfirmedAt": null,
"productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
"optionId": "DEFAULT",
"cancellable": true,
"cancellation": null,
"freesale": false,
"notes": "optional notes on the booking",
"availability": {
"id": "2020-07-01T14:30:00-05:00",
"localDateTimeStart": "2020-07-01T14:30:00-05:00",
"localDateTimeEnd": "2020-07-02T02:30:00-05:00",
"allDay": true,
"openingHours": []
},
"contact": {
"fullName": null,
"emailAddress": null,
"phoneNumber": null,
"locales": [],
"country": null
},
"deliveryMethods": [
"VOUCHER",
"TICKET"
],
"voucher": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
},
"unitItems": [
{
"uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
"resellerReference": null,
"supplierReference": "408H44",
"unitId": "child",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
},
{
"uuid": "ec1e2622-1359-437b-83f8-15182759d605",
"resellerReference": null,
"supplierReference": "BSDYM4",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
},
{
"uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
"resellerReference": null,
"supplierReference": "E5K92G",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
}
]
}

The request above was made with the following request body:

{
"productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
"optionId": "DEFAULT",
"availabilityId": "2020-07-01T14:30:00-05:00",
"notes": "Optional notes for the booking",
"unitItems": [
{ "unitId": "adult" },
{ "unitId": "adult" },
{ "unitId": "child" }
]
}

The UUID on the request body and on each unit is optional but recommended if you're requesting from a source of poor network connectivity. If the connection fails or you do not receive a response, you can repeat the same request with the same UUID and it will respond with the same booking object without duplicating the booking.

The booking object is described as:

Field

Description

uuid

A unique UUID used to identify booking. Make sure you save this value as you will need it to perform any future actions against this booking.

testMode

Whether this booking is in test mode.

resellerReference

Your reference (as the reseller). You set this value in the second confirmation request.

supplierReference

The ventrata reference for this booking. Use this to help the supplier find this booking.

status

The status of the booking, possible values are:

ON_HOLD The booking is pending confirmation, this is the default value when you first create the booking.

EXPIRED If the booking is not confirmed before the expiration hold expires, it goes into an expired state. CONFIRMED Once the confirmation call is made the booking is ready to be used. CANCELLED If the booking is cancelled.

utcExpiresAt

An ISO8601 date time in UTC for when this booking is due to expire if the status is ON_HOLD

utcConfirmedAt

An ISO8601 date time in UTC when the booking was confirmed.

productId

The product ID for this booking

optionId

The option ID for this booking

cancellable

A boolean field indicating whether this booking can be cancelled.

cancellation

An object with information about why and when the booking was cancelled. This is null if the booking is not cancelled.

freesale

Whether the booking was made as freesale (without checking availability first).

notes

Public notes on the booking.

cancellation.reason

A text value describing why the cancellation happened.

cancellation.refund

Whether the booking was refunded as part of the cancellation. Possible values are FULL, PARTIAL or NONE

cancellation.utcCancelledAt

An ISO8601 date time in UTC indicating when the booking was cancelled.

availability

The availability object that was booked.

availability.id

The availability id that was used in the request.

availability.localDateTimeStart

The localDateTimeStart value from the original availability object.

availability.localDateTimeEnd

The localDateTimeEnd value from the original availability object.

availability.allDay

A boolean value indicating whether the availability is all day.

availability.openingHours

The opening hours from the original availability object.

contact

The customer contact details. These values are set in the booking confirmation step.

contact.fullName

The full name of the guest

contact.emailAddress

The email of the guest

contact.phoneNumber

The phone number of the guest

contact.locales

An array of locale values, equivalent to navigator.languages in a browsers environment.

deliveryMethods

An array of delivery methods available for this booking. Possible values are:

VOUCHER The voucher object is populated which is a single ticket for the whole booking.

TICKET The ticket object is populated on each unit item which is a ticket for each individual person.

voucher

This value will be set if deliveryMethods array has VOUCHER as one of the values.

voucher.redemptionMethod

How the voucher can be redeemed. Possible values are:

MANIFEST The guest name will be written down and they just need to show up

DIGITAL The tickets/voucher must be scanned but can be on mobile

PRINT The tickets/voucher must be printed and presented on arrival

voucher.utcRdeemedAt

The ISO8601 date in UTC indicating when the voucher was used at the attraction.

voucher.deliveryOptions

This is an array of delivery options for the voucher each object. You should use one of these to give the tickets to the guest.

voucher.deliveryOptions[].deliveryFormat

The format for the delivery option possible values are:

QRCODE You should generate the QR Code yourself on a ticket.

PDF_URL Where you use the Ventrata generated tickets as a PDF.

voucher.deliveryOptions[].deliveryValue

Depending on the value of deliveryFormat this value is either:

QRCODE This value is a string to encode in a QR Code.

PDF_URL This value is a URL linking to a ventrata generated voucher PDF.

unitItems

This is an array of unit items generated when making the booking.

unitItems[].uuid

A unique UUID per unit item that you can use to help track it.

unitItems[].resellerReference

Your reference (as a reseller) for this unit item.

unitItem[].supplierReference

The ventrata reference for this unit item.

unitItems[].unitId

The unit id used for this unit item

unitItem[].ticket

If deliveryMethods has TICKET as one of its values this object will be set. The data structure will be identical to the voucher object.

The booking object schema described above will be returned on every endpoint in this section. Only the values may change.

patch
Booking Update

https://api.ventrata.com/octo/bookings/:uuid
This endpoint allows you to update an existing booking. The request parameters are the same as the booking reservation endpoint.
Request
Response
Request
Path Parameters
:uuid
required
string
The booking uuid
Response
200: OK
{
"uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
"testMode": true,
"resellerReference": null,
"supplierReference": "X749G9",
"status": "ON_HOLD",
"utcExpiresAt": "2020-06-07T17:06:37Z",
"utcConfirmedAt": null,
"productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
"optionId": "DEFAULT",
"cancellable": true,
"cancellation": null,
"freesale": false,
"notes": "Optional notes on the booking",
"availability": {
"id": "2020-07-01T14:30:00-05:00",
"localDateTimeStart": "2020-07-01T14:30:00-05:00",
"localDateTimeEnd": "2020-07-02T02:30:00-05:00",
"allDay": true,
"openingHours": []
},
"contact": {
"fullName": null,
"emailAddress": null,
"phoneNumber": null,
"locales": [],
"country": null
},
"deliveryMethods": [
"VOUCHER",
"TICKET"
],
"voucher": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
},
"unitItems": [
{
"uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
"resellerReference": null,
"supplierReference": "408H44",
"unitId": "child",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
},
{
"uuid": "ec1e2622-1359-437b-83f8-15182759d605",
"resellerReference": null,
"supplierReference": "BSDYM4",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
},
{
"uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
"resellerReference": null,
"supplierReference": "E5K92G",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
}
]
}

You can update a booking before and after it has been confirmed as long as it hasn't been redeemed or within the cancellation cutoff window. To know if the booking can be updated check the booking.cancellable field. If the booking can be cancelled, it can also be updated. It's generally preferred to update a booking rather than cancelling it and rebooking.

post
Booking Confirmation

https://api.ventrata.com/octo/bookings/:uuid/confirm
This endpoint confirms the booking so it's ready to be used.
Request
Response
Request
Path Parameters
uuid
required
string
The UUID of the booking
Body Parameters
emailReceipt
optional
boolean
Whether you want Ventrata to email the guest a copy of their receipt and tickets. (defaults to false)
resellerReference
optional
string
Your reference for this booking. Also known as a Voucher Number.
contact
optional
object
Contact information
contact.fullName
optional
string
The customer's full name
contact.emailAddress
optional
string
The customer's email
contact.phoneNumber
optional
string
The customer's phone number
contact.locales
optional
array
An array of customer's locales. You can get this from `navigator.languages` in a browser context.
contact.country
optional
string
The customer's country code
Response
200: OK
{
"uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
"testMode": true,
"resellerReference": "VOUCHER-0123",
"supplierReference": "X749G9",
"status": "CONFIRMED",
"utcExpiresAt": null,
"utcConfirmedAt": "2020-06-07T18:36:29Z",
"productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
"optionId": "DEFAULT",
"cancellable": true,
"cancellation": null,
"freesale": false,
"notes": "Optional notes on the booking",
"availability": {
"id": "2020-06-27T00:00:00+02:00",
"localDateTimeStart": "2020-06-27T00:00:00+02:00",
"localDateTimeEnd": "2020-06-28T00:00:00+02:00",
"allDay": true,
"openingHours": []
},
"contact": {
"fullName": "Oliver Morgan",
"emailAddress": "ollym@me.com",
"phoneNumber": "+447840739436",
"locales": ["en-GB", "en-US", "en"],
"country": "GB"
},
"deliveryMethods": [
"VOUCHER",
"TICKET"
],
"voucher": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": [
{
"deliveryFormat": "QRCODE",
"deliveryValue": "!1|zmEIG9t4f8x4qyhYcMkV8oPCQcZhgcOfKc1cJcvcl|mwhjfBi9hZlRDzAsjLkz5m|Zar+nrHcNn/CR1Gp"
},
{
"deliveryFormat": "PDF_URL",
"deliveryValue": "http://api.ventrata.localhost:3000/octo/pdf?booking=50a54a87-3fe3-4a1b-8409-15d4de0e7d41"
}
]
},
"unitItems": [
{
"uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
"resellerReference": null,
"supplierReference": "408H44",
"unitId": "child",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": [
{
"deliveryFormat": "QRCODE",
"deliveryValue": "!1|y8DI7kHZfKB3qNiBc8oAVLpsDfyflcmcKcBc6cJcg|mwhjfBi9hZlRDzAsjLkz5m|cS1MkoKTmFnBwT6B"
},
{
"deliveryFormat": "PDF_URL",
"deliveryValue": "https://api.ventrata.com/octo/pdf?booking=50a54a87-3fe3-4a1b-8409-15d4de0e7d41&ticket=3def6f63-3d7c-4f66-b2a1-32d202493a52"
}
]
}
},
{
"uuid": "ec1e2622-1359-437b-83f8-15182759d605",
"resellerReference": null,
"supplierReference": "BSDYM4",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": [
{
"deliveryFormat": "QRCODE",
"deliveryValue": "!1|zmEIG9t4f8x4qyhYcMkV8oPCPhDfgcJcKc1cJcvcl|mwhjfBi9hZlRDzAsjLkz5m|VgmSJOhfTnAeO7pt"
},
{
"deliveryFormat": "PDF_URL",
"deliveryValue": "https://api.ventrata.com/octo/pdf?booking=50a54a87-3fe3-4a1b-8409-15d4de0e7d41&ticket=9bcc82c9-4c75-4a86-aa1f-b25f397953a1"
}
]
}
},
{
"uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
"resellerReference": null,
"supplierReference": "E5K92G",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": [
{
"deliveryFormat": "QRCODE",
"deliveryValue": "!1|An2IZ2hGfxpwlXCkcWRZ5A8flimcqc2fncmcAcKcl|mwhjfBi9hZlRDzAsjLkz5m|aTDanPYLWocA94cw"
},
{
"deliveryFormat": "PDF_URL",
"deliveryValue": "https://api.ventrata.com/octo/pdf?booking=50a54a87-3fe3-4a1b-8409-15d4de0e7d41&ticket=34cda40a-0807-4e03-9968-22b7e20b0561"
}
]
}
}
]
}

An example of the confirmation request above looks like this:

{
"resellerReference": "VOUCHER-0123",
"contact": {
"fullName": "Oliver Morgan",
"emailAddress": "ollym@me.com",
"phoneNumber": "+447840739436",
"locales": ["en-GB", "en-US", "en"],
"country": "GB"
}
}

Once the booking is confirmed, the delivery options of both the voucher and/or ticket are populated. An example of the values is shown below:

//...inside either "voucher" and/or "ticket"
‚Äč
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": [
{
"deliveryFormat": "QRCODE",
"deliveryValue": "!1|zmEIG9t4f8x4qyhYcMkV8oPCQcZhgcOfKc1cJcvcl|mwhjfBi9hZlRDzAsjLkz5m|Zar+nrHcNn/CR1Gp"
},
{
"deliveryFormat": "PDF_URL",
"deliveryValue": "https://api.ventrata.com/octo/pdf?booking=50a54a87-3fe3-4a1b-8409-15d4de0e7d41"
}
]

If booking.deliveryMethods contains both TICKET and VOUCHER then both those values will be set. You can then offer the guest whether they'd like their tickets per-person (booking.unitItems[].ticket) or one for the whole booking (booking.voucher). If you're unable to offer the voice then it's suggested you default to one falling back to the other if that's not available.

delete
Booking Cancellation

https://api.ventrata.com/octo/bookings/:uuid
If the booking is confirmed this endpoint will cancel it, otherwise it will release the availability that was put on hold.
Request
Response
Request
Path Parameters
:uuid
required
string
The UUID of the booking
Body Parameters
reason
optional
string
The reason for cancelling the booking
Response
200: OK
{
"uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
"testMode": true,
"resellerReference": null,
"supplierReference": "X749G9",
"status": "CANCELLED",
"utcExpiresAt": "2020-06-07T17:06:37Z",
"utcConfirmedAt": null,
"productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
"optionId": "DEFAULT",
"cancellable": true,
"cancellation": {
"refund": "FULL",
"reason": "Customer Requested"
"utcCancelledAt": "2020-06-07T18:36:29Z"
},
"availability": {
"id": "2020-07-01T14:30:00-05:00",
"localDateTimeStart": "2020-07-01T14:30:00-05:00",
"localDateTimeEnd": "2020-07-02T02:30:00-05:00",
"allDay": true,
"openingHours": []
},
"contact": {
"fullName": "Oliver Morgan",
"emailAddress": "ollym@me.com",
"phoneNumber": "+447840739436",
"locales": ["en-GB", "en-US", "en"],
"country": "GB"
},
"deliveryMethods": [
"VOUCHER",
"TICKET"
],
"voucher": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"utcDeliveredAt": null,
"deliveryOptions": []
},
"unitItems": [
{
"uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
"resellerReference": null,
"supplierReference": "408H44",
"unitId": "child",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"utcDeliveredAt": null,
"deliveryOptions": []
}
},
{
"uuid": "ec1e2622-1359-437b-83f8-15182759d605",
"resellerReference": null,
"supplierReference": "BSDYM4",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"utcDeliveredAt": null,
"deliveryOptions": []
}
},
{
"uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
"resellerReference": null,
"supplierReference": "E5K92G",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"utcDeliveredAt": null,
"deliveryOptions": []
}
}
]
}

Note you can only cancel a booking if booking.cancellable is true.

post
Extend Reservation

https://api.ventrata.com/octo/bookings/:uuid/extend
Use this method to hold the availability for a booking longer if the status is `ON_HOLD`.
Request
Response
Request
Path Parameters
:uuid
required
string
The UUID of the original booking
Body Parameters
expirationMinutes
optional
integer
How many minutes from now do you want to have the booking reserved for.
Response
200: OK
{
"uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
"testMode": true,
"resellerReference": null,
"supplierReference": "X749G9",
"status": "ON_HOLD",
"utcExpiresAt": "2020-06-07T17:06:37Z",
"utcConfirmedAt": null,
"productId": "1a7213eb-3a33-4cbb-b114-64d771c201ac",
"optionId": "DEFAULT",
"cancellable": true,
"cancellation": null,
"freesale": false,
"availability": {
"id": "2020-07-01T14:30:00-05:00",
"localDateTimeStart": "2020-07-01T14:30:00-05:00",
"localDateTimeEnd": "2020-07-02T02:30:00-05:00",
"allDay": true,
"openingHours": []
},
"contact": {
"fullName": null,
"emailAddress": null,
"phoneNumber": null,
"locales": [],
"country": null
},
"deliveryMethods": [
"VOUCHER",
"TICKET"
],
"voucher": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
},
"unitItems": [
{
"uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f",
"resellerReference": null,
"supplierReference": "408H44",
"unitId": "child",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
},
{
"uuid": "ec1e2622-1359-437b-83f8-15182759d605",
"resellerReference": null,
"supplierReference": "BSDYM4",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
},
{
"uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb",
"resellerReference": null,
"supplierReference": "E5K92G",
"unitId": "adult",
"ticket": {
"redemptionMethod": "DIGITAL",
"utcRedeemedAt": null,
"deliveryOptions": []
}
}
]
}