Booking
Reserving availability an making a booking
The steps to making a booking are as follows:
  1. 1.
    Check Availability Check the availability in the previous section and retrieve an availability ID. **
  2. 2.
    Booking Reservation Create a booking that reserves the availability while you collect payment and contact information from the customer.
  3. 3.
    Booking Confirmation The final step, once payment has been taken and you want to finalise the booking.
post
https://api.ventrata.com/octo
/bookings
Booking Reservation
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.
The booking object schema described above will be returned on every endpoint in this section. Only the values may change.
patch
https://api.ventrata.com/octo
/bookings/:uuid
Booking Update
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
https://api.ventrata.com/octo
/bookings/:uuid/confirm
Booking Confirmation
An example of the confirmation request above looks like this:
{
"resellerReference": "VOUCHER-0123",
"contact": {
"fullName": "Oliver Morgan",
"emailAddress": "[email protected]",
"phoneNumber": "+447840739436",
"locales": ["en-GB", "en-US", "en"],
"country": "GB"
}
}
Optionally, if you want to provide contact details or a reseller reference for each unit item, you can confirm the booking and repeat the unit items including the contact details for each one like this:
{
"resellerReference": "VOUCHER-0123",
"contact": {
"fullName": "Oliver Morgan",
"emailAddress": "[email protected]",
"phoneNumber": "+447840739436",
"locales": ["en-GB", "en-US", "en"],
"country": "GB"
},
"unitItems": [
{
"resellerReference": "VOUCHER-0123-1",
"unitId": "adult",
"contact": {
"fullName": "Oliver Morgan"
}
},
{
"resellerReference": "VOUCHER-0123-2",
"unitId": "adult",
"contact": {
"fullName": "Alicia Smith"
}
},
{
"resellerReference": "VOUCHER-0123-3",
"unitId": "child",
"contact": {
"fullName": "Tomasz Karbownicki"
}
}
]
}
Be careful to make sure you include ALL unit items that you also had in the original booking reservation request, if you provide more or less than in the booking reservation call this will change the number of unit items being purchased also.
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
https://api.ventrata.com/octo
/bookings/:uuid
Booking Cancellation
Note you can only cancel a booking if booking.cancellable is true.
post
https://api.ventrata.com/octo
/bookings/:uuid/extend
Extend Reservation
get
https://api.ventrata.com/octo
/bookings/:uuid
Get Booking
This endpoint will fetch the booking with the provided UUID from the system.
get
https://api.ventrata.com/octo
/bookings
List Bookings
When using this endpoint you must include one of the following parameters:
  • resellerReference
  • supplierReference
  • localDate
  • localDateStart and localDateEnd
Then in addition you can also add productId and optionId
The results aren't paginated as the result set will never be too long because of the required filters.
Last modified 6mo ago