Bookings

Booking Reservation

A reseller has to perform Availability Check to retrieve an availabilityId in order to make a Booking Reservation.

Booking Reservation

Reserving availability when making a booking. The steps to make a reservation are:

1. Check Availability: Check the availability on the /availability endpoint to retrieve an availabilityId
2. Booking Reservation (this step): Create a booking that reserves the availability while you collect payment and contact information from the customer. The booking will remain with status ON_HOLD until the booking is confirmed or the reservation hold expires.

The availability for the booking is held for the amount of time equal to theexpirationMinutes parameter (if provided), up to an internal limit set by either the supplier or the OCTo provider. The utc_expires_at parameter in the response object will indicate when a reservtion will expire. A reservation can be extended by calling the /bookings/{uuid}/extend endpoint.

A reserved booking can be confirmed after the customer finalizes their choice on the /bookings/{uuid}/confirm endpoint provided the reservation had not expired.

POSThttps://api.example.com/octo/bookings

Header parameters

Body

application/json

uuidstring (uuid)

A unique UUID to identify the booking. Setting this value acts like an idempotency key preventing you from double booking.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

productId*string

The product ID for this booking.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

optionId*string

The option ID for this booking.

Example: "DEFAULT"

availabilityId*string

The availability ID for the selected timeslot.

Example: "2021-10-27T00:00:00-04:00"

expirationMinutesinteger

How many minutes to reserve the availability, otherwise defaults to the supplier default amount.

Example: 30

notesstring

Optional notes for the booking.

Example: "Optional notes"

unitItems*array of object

An list of unit items that will be included in the booking.

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "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"
        }
      ]
    }),
});
const data = await response.json();

Response

200400

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "testMode": false,
  "status": "CONFIRMED",
  "utcCreatedAt": "2021-10-27T23:28:43Z",
  "utcUpdatedAt": "2021-10-27T23:28:43Z",
  "utcExpiresAt": "2021-10-27T23:58:43Z",
  "utcConfirmedAt": "2021-10-27T23:28:43Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "Amazon River Tour",
    "reference": "AMZN",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": false,
    "instantConfirmation": false,
    "instantDelivery": false,
    "availabilityRequired": false,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "VOUCHER"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": false,
        "internalName": "Private Morning Tour",
        "reference": "VIP-MORN",
        "availabilityLocalStartTimes": [
          "09:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 10
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult(s)",
            "reference": "LR1-01-new",
            "type": "YOUTH",
            "requiredContactFields": [
              "firstName"
            ],
            "restrictions": {
              "minAge": 3,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": 2,
              "maxQuantity": 7,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            }
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": false,
    "internalName": "Private Morning Tour",
    "reference": "VIP-MORN",
    "availabilityLocalStartTimes": [
      "09:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 10
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      }
    ]
  },
  "cancellable": false,
  "cancellation": {
    "refund": "text",
    "utcCancelledAt": "2021-10-27T23:38:43Z"
  },
  "freesale": false,
  "availabilityId": "text",
  "availability": {
    "id": "2021-10-27T00:00:00-04:00",
    "localDateTimeStart": "2021-10-27T00:00:00-04:00",
    "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
    "allDay": false,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[e-mail]",
    "locales": [
      "en"
    ]
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": "text"
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
      "supplierReference": "K9T7R5",
      "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      },
      "status": "CONFIRMED",
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "[e-mail]",
        "locales": [
          "en"
        ]
      },
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "text"
          }
        ]
      }
    }
  ]
}

Booking Confirmation

Booking Confirmation

This endpoint confirms the booking so it's ready to be used.

POSThttps://api.example.com/octo/bookings/{uuid}/confirm

Authorization

Auth

Path parameters

uuid*string

The UUID of the booking

Header parameters

Body

application/json

emailReceiptboolean

Whether you want OCTO Cloud to email the guest a copy of their receipt and tickets. (defaults to false)

resellerReferencestring

Your reference for this booking. Also known as a Voucher Number.

Example: "4ec08a62-892c-48c1-a608-dc946531a33b"

contact*object

Contact details for the main guest who will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information).

unitItemsarray of object

An array of unit items that will be included in the booking. This allows you to provide contact details or a reseller reference for each unit item. 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.

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings/{uuid}/confirm', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "resellerReference": "VOUCHER-0123",
      "contact": {
        "fullName": "Oliver Morgan",
        "emailAddress": "[e-mail]",
        "phoneNumber": "[phone]",
        "locales": [
          "en-GB",
          "en-US",
          "en"
        ],
        "country": "GB"
      }
    }),
});
const data = await response.json();

Response

200400

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "testMode": false,
  "status": "CONFIRMED",
  "utcCreatedAt": "2021-10-27T23:28:43Z",
  "utcUpdatedAt": "2021-10-27T23:28:43Z",
  "utcExpiresAt": "2021-10-27T23:58:43Z",
  "utcConfirmedAt": "2021-10-27T23:28:43Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "Amazon River Tour",
    "reference": "AMZN",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": false,
    "instantConfirmation": false,
    "instantDelivery": false,
    "availabilityRequired": false,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "VOUCHER"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": false,
        "internalName": "Private Morning Tour",
        "reference": "VIP-MORN",
        "availabilityLocalStartTimes": [
          "09:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 10
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult(s)",
            "reference": "LR1-01-new",
            "type": "YOUTH",
            "requiredContactFields": [
              "firstName"
            ],
            "restrictions": {
              "minAge": 3,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": 2,
              "maxQuantity": 7,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            }
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": false,
    "internalName": "Private Morning Tour",
    "reference": "VIP-MORN",
    "availabilityLocalStartTimes": [
      "09:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 10
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      }
    ]
  },
  "cancellable": false,
  "cancellation": {
    "refund": "text",
    "utcCancelledAt": "2021-10-27T23:38:43Z"
  },
  "freesale": false,
  "availabilityId": "text",
  "availability": {
    "id": "2021-10-27T00:00:00-04:00",
    "localDateTimeStart": "2021-10-27T00:00:00-04:00",
    "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
    "allDay": false,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[e-mail]",
    "locales": [
      "en"
    ]
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": "text"
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
      "supplierReference": "K9T7R5",
      "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      },
      "status": "CONFIRMED",
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "[e-mail]",
        "locales": [
          "en"
        ]
      },
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "text"
          }
        ]
      }
    }
  ]
}

Booking Cancellation

Booking Cancellation

For cancelling bookings. You can only cancel a booking if booking.cancellable is TRUE, and is within the booking cancellation cut-off window.

POSThttps://api.example.com/octo/bookings/{uuid}/cancel

Header parameters

Body

application/json

reasonstring

A text value describing why the cancellation happened.

Example: "Customer Requested"

forceboolean

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings/{uuid}/cancel', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "reason": "Customer Requested"
    }),
});
const data = await response.json();

Response

200400

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "testMode": false,
  "status": "CONFIRMED",
  "utcCreatedAt": "2021-10-27T23:28:43Z",
  "utcUpdatedAt": "2021-10-27T23:28:43Z",
  "utcExpiresAt": "2021-10-27T23:58:43Z",
  "utcConfirmedAt": "2021-10-27T23:28:43Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "Amazon River Tour",
    "reference": "AMZN",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": false,
    "instantConfirmation": false,
    "instantDelivery": false,
    "availabilityRequired": false,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "VOUCHER"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": false,
        "internalName": "Private Morning Tour",
        "reference": "VIP-MORN",
        "availabilityLocalStartTimes": [
          "09:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 10
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult(s)",
            "reference": "LR1-01-new",
            "type": "YOUTH",
            "requiredContactFields": [
              "firstName"
            ],
            "restrictions": {
              "minAge": 3,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": 2,
              "maxQuantity": 7,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            }
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": false,
    "internalName": "Private Morning Tour",
    "reference": "VIP-MORN",
    "availabilityLocalStartTimes": [
      "09:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 10
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      }
    ]
  },
  "cancellable": false,
  "cancellation": {
    "refund": "text",
    "utcCancelledAt": "2021-10-27T23:38:43Z"
  },
  "freesale": false,
  "availabilityId": "text",
  "availability": {
    "id": "2021-10-27T00:00:00-04:00",
    "localDateTimeStart": "2021-10-27T00:00:00-04:00",
    "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
    "allDay": false,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[e-mail]",
    "locales": [
      "en"
    ]
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": "text"
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
      "supplierReference": "K9T7R5",
      "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      },
      "status": "CONFIRMED",
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "[e-mail]",
        "locales": [
          "en"
        ]
      },
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "text"
          }
        ]
      }
    }
  ]
}

Get Bookings

Get Bookings

This endpoint will fetch the bookings you have made for the given filters.

When using this endpoint you must include one of the following query parameters:

• resellerReference
• supplierReference
• localDate
• localDateStart and localDateEnd

GEThttps://api.example.com/octo/bookings

Authorization

Auth

Query parameters

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200400

[
  {
    "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
    "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
    "testMode": false,
    "status": "CONFIRMED",
    "utcCreatedAt": "2021-10-27T23:28:43Z",
    "utcUpdatedAt": "2021-10-27T23:28:43Z",
    "utcExpiresAt": "2021-10-27T23:58:43Z",
    "utcConfirmedAt": "2021-10-27T23:28:43Z",
    "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "product": {
      "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
      "internalName": "Amazon River Tour",
      "reference": "AMZN",
      "locale": "en-GB",
      "timeZone": "Europe/London",
      "allowFreesale": false,
      "instantConfirmation": false,
      "instantDelivery": false,
      "availabilityRequired": false,
      "availabilityType": "START_TIME",
      "deliveryFormats": [
        "QRCODE"
      ],
      "deliveryMethods": [
        "VOUCHER"
      ],
      "redemptionMethod": "DIGITAL",
      "options": [
        {
          "id": "DEFAULT",
          "default": false,
          "internalName": "Private Morning Tour",
          "reference": "VIP-MORN",
          "availabilityLocalStartTimes": [
            "09:00"
          ],
          "cancellationCutoff": "1 hour",
          "cancellationCutoffAmount": 1,
          "cancellationCutoffUnit": "hour",
          "requiredContactFields": [
            "firstName"
          ],
          "restrictions": {
            "minUnits": 0,
            "maxUnits": 10
          },
          "units": [
            {
              "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
              "internalName": "Adult(s)",
              "reference": "LR1-01-new",
              "type": "YOUTH",
              "requiredContactFields": [
                "firstName"
              ],
              "restrictions": {
                "minAge": 3,
                "maxAge": 17,
                "idRequired": false,
                "minQuantity": 2,
                "maxQuantity": 7,
                "paxCount": 1,
                "accompaniedBy": [
                  "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
                ]
              }
            }
          ]
        }
      ]
    },
    "optionId": "DEFAULT",
    "option": {
      "id": "DEFAULT",
      "default": false,
      "internalName": "Private Morning Tour",
      "reference": "VIP-MORN",
      "availabilityLocalStartTimes": [
        "09:00"
      ],
      "cancellationCutoff": "1 hour",
      "cancellationCutoffAmount": 1,
      "cancellationCutoffUnit": "hour",
      "requiredContactFields": [
        "firstName"
      ],
      "restrictions": {
        "minUnits": 0,
        "maxUnits": 10
      },
      "units": [
        {
          "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
          "internalName": "Adult(s)",
          "reference": "LR1-01-new",
          "type": "YOUTH",
          "requiredContactFields": [
            "firstName"
          ],
          "restrictions": {
            "minAge": 3,
            "maxAge": 17,
            "idRequired": false,
            "minQuantity": 2,
            "maxQuantity": 7,
            "paxCount": 1,
            "accompaniedBy": [
              "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
            ]
          }
        }
      ]
    },
    "cancellable": false,
    "cancellation": {
      "refund": "text",
      "utcCancelledAt": "2021-10-27T23:38:43Z"
    },
    "freesale": false,
    "availabilityId": "text",
    "availability": {
      "id": "2021-10-27T00:00:00-04:00",
      "localDateTimeStart": "2021-10-27T00:00:00-04:00",
      "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
      "allDay": false,
      "openingHours": [
        {
          "from": "08:00",
          "to": "16:00"
        }
      ]
    },
    "contact": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "emailAddress": "[e-mail]",
      "locales": [
        "en"
      ]
    },
    "notes": "Optional notes for the booking",
    "deliveryMethods": [
      "VOUCHER"
    ],
    "voucher": {
      "redemptionMethod": "DIGITAL",
      "deliveryOptions": [
        {
          "deliveryFormat": "QRCODE",
          "deliveryValue": "text"
        }
      ]
    },
    "unitItems": [
      {
        "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
        "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
        "supplierReference": "K9T7R5",
        "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
        "unit": {
          "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
          "internalName": "Adult(s)",
          "reference": "LR1-01-new",
          "type": "YOUTH",
          "requiredContactFields": [
            "firstName"
          ],
          "restrictions": {
            "minAge": 3,
            "maxAge": 17,
            "idRequired": false,
            "minQuantity": 2,
            "maxQuantity": 7,
            "paxCount": 1,
            "accompaniedBy": [
              "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
            ]
          }
        },
        "status": "CONFIRMED",
        "contact": {
          "fullName": "John Doe",
          "firstName": "John",
          "lastName": "Doe",
          "emailAddress": "[e-mail]",
          "locales": [
            "en"
          ]
        },
        "ticket": {
          "redemptionMethod": "DIGITAL",
          "deliveryOptions": [
            {
              "deliveryFormat": "QRCODE",
              "deliveryValue": "text"
            }
          ]
        }
      }
    ]
  }
]

Get Booking

Get Booking

Fetch the status of an existing booking.

GEThttps://api.example.com/octo/bookings/{uuid}

Path parameters

uuid*string

The UUID of the booking

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings/{uuid}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "testMode": false,
  "status": "CONFIRMED",
  "utcCreatedAt": "2021-10-27T23:28:43Z",
  "utcUpdatedAt": "2021-10-27T23:28:43Z",
  "utcExpiresAt": "2021-10-27T23:58:43Z",
  "utcConfirmedAt": "2021-10-27T23:28:43Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "Amazon River Tour",
    "reference": "AMZN",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": false,
    "instantConfirmation": false,
    "instantDelivery": false,
    "availabilityRequired": false,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "VOUCHER"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": false,
        "internalName": "Private Morning Tour",
        "reference": "VIP-MORN",
        "availabilityLocalStartTimes": [
          "09:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 10
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult(s)",
            "reference": "LR1-01-new",
            "type": "YOUTH",
            "requiredContactFields": [
              "firstName"
            ],
            "restrictions": {
              "minAge": 3,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": 2,
              "maxQuantity": 7,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            }
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": false,
    "internalName": "Private Morning Tour",
    "reference": "VIP-MORN",
    "availabilityLocalStartTimes": [
      "09:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 10
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      }
    ]
  },
  "cancellable": false,
  "cancellation": {
    "refund": "text",
    "utcCancelledAt": "2021-10-27T23:38:43Z"
  },
  "freesale": false,
  "availabilityId": "text",
  "availability": {
    "id": "2021-10-27T00:00:00-04:00",
    "localDateTimeStart": "2021-10-27T00:00:00-04:00",
    "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
    "allDay": false,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[e-mail]",
    "locales": [
      "en"
    ]
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": "text"
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
      "supplierReference": "K9T7R5",
      "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      },
      "status": "CONFIRMED",
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "[e-mail]",
        "locales": [
          "en"
        ]
      },
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "text"
          }
        ]
      }
    }
  ]
}

Booking Update

Booking Update

Updates 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''s 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.

PATCHhttps://api.example.com/octo/bookings/{uuid}

Path parameters

uuid*string

The UUID of the booking

Header parameters

Body

application/json

resellerReferencestring

Your reference for this booking. Also known as a Voucher Number.

Example: "ec08a62-892c-48c1-a608-dc946531a33b"

productIdstring

The product ID.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

optionIdstring

The option id.

Example: "DEFAULT"

availabilityIdstring

The availability ID for the selected timeslot.

expirationMinutesstring

How many minutes to reserve the availability, otherwise defaults to the supplier default amount.

notesstring

Optional notes for the booking.

emailReceiptboolean

Whether you want OCTO Cloud to email the guest a copy of their receipt and tickets. (defaults to false).

unitItemsarray of object

An array of unit items in the booking. To retain or modify existing unit items, you must include the unit item with the associated uuid, otherwise that unit item will be removed.

contactobject

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings/{uuid}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "testMode": false,
  "status": "CONFIRMED",
  "utcCreatedAt": "2021-10-27T23:28:43Z",
  "utcUpdatedAt": "2021-10-27T23:28:43Z",
  "utcExpiresAt": "2021-10-27T23:58:43Z",
  "utcConfirmedAt": "2021-10-27T23:28:43Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "Amazon River Tour",
    "reference": "AMZN",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": false,
    "instantConfirmation": false,
    "instantDelivery": false,
    "availabilityRequired": false,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "VOUCHER"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": false,
        "internalName": "Private Morning Tour",
        "reference": "VIP-MORN",
        "availabilityLocalStartTimes": [
          "09:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 10
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult(s)",
            "reference": "LR1-01-new",
            "type": "YOUTH",
            "requiredContactFields": [
              "firstName"
            ],
            "restrictions": {
              "minAge": 3,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": 2,
              "maxQuantity": 7,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            }
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": false,
    "internalName": "Private Morning Tour",
    "reference": "VIP-MORN",
    "availabilityLocalStartTimes": [
      "09:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 10
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      }
    ]
  },
  "cancellable": false,
  "cancellation": {
    "refund": "text",
    "utcCancelledAt": "2021-10-27T23:38:43Z"
  },
  "freesale": false,
  "availabilityId": "text",
  "availability": {
    "id": "2021-10-27T00:00:00-04:00",
    "localDateTimeStart": "2021-10-27T00:00:00-04:00",
    "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
    "allDay": false,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[e-mail]",
    "locales": [
      "en"
    ]
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": "text"
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
      "supplierReference": "K9T7R5",
      "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      },
      "status": "CONFIRMED",
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "[e-mail]",
        "locales": [
          "en"
        ]
      },
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "text"
          }
        ]
      }
    }
  ]
}

Extend Reservation

Extend Reservation

Use this endpoint to hold the availability for a booking longer if the status is ON_HOLD.

POSThttps://api.example.com/octo/bookings/{uuid}/extend

Authorization

Auth

Path parameters

uuid*string

The UUID of the booking

Header parameters

Body

application/json

expirationMinutesinteger

Example: 15

Response

200400

OK

Body

application/json

id*string

A unique ID / UUID generated by the supplier system to identify the booking.

Example: "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea"

uuid*string (uuid)

A UUID you can set when generating the booking to use as an idempotency key.

Example: "559aed3d-6d5b-4fe0-bfca-99f5e7218a56"

testMode*boolean

If TRUE, booking was created on test mode

resellerReference*stringnull

The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.

supplierReference*stringnull

The Supplier's / booking platform reference.

status*BookingStatus

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. PENDING If the booking is pending outside availability confirmation. REDEEMED If the booking is already redeemed.

Example: "CONFIRMED"

ON_HOLDCONFIRMEDEXPIREDCANCELLEDREDEEMEDPENDINGREJECTED

utcCreatedAt*string

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

Example: "2021-10-27T23:28:43Z"

utcUpdatedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

utcExpiresAt*stringnull

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

Example: "2021-10-27T23:58:43Z"

utcRedeemedAt*stringnull

An ISO8601 date time in UTC at when the booking was redeemed.

utcConfirmedAt*stringnull

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

Example: "2021-10-27T23:28:43Z"

productId*string

The product ID that identifies the product in the booking system to make this reservation.

Example: "6b903d44-dc24-4ca4-ae71-6bde6c4f4854"

product*object

A bookable product listed by a supplier.

optionId*string

The product ID that identifies the product option in the booking system to make this reservation.

Example: "DEFAULT"

option*object

Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.

cancellable*boolean

A boolean field indicating whether this booking can be cancelled.

cancellation*nullobject

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

freesale*boolean

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

availabilityId*string

The availability id that was used in the request.

availability*object

The availability object that was booked.

contact*object

Contact details for the guests that will attend the tour/attraction. Contact schema can be applied to both the booking object (the main reservation) or the unit object (individual ticket holders - if the supplier requires this information)

notes*stringnull

Example: "Optional notes for the booking"

deliveryMethods*array of DeliveryMethod

An array of delivery methods available for this booking.

voucherone of

objectnull

unitItems*array of object

An array of unit items that will be included in the booking.

Request

JavaScriptCurlPython

const response = await fetch('https://api.example.com/octo/bookings/{uuid}/extend', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "expirationMinutes": 0
    }),
});
const data = await response.json();

Response

200400

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "testMode": false,
  "status": "CONFIRMED",
  "utcCreatedAt": "2021-10-27T23:28:43Z",
  "utcUpdatedAt": "2021-10-27T23:28:43Z",
  "utcExpiresAt": "2021-10-27T23:58:43Z",
  "utcConfirmedAt": "2021-10-27T23:28:43Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "Amazon River Tour",
    "reference": "AMZN",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": false,
    "instantConfirmation": false,
    "instantDelivery": false,
    "availabilityRequired": false,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "VOUCHER"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": false,
        "internalName": "Private Morning Tour",
        "reference": "VIP-MORN",
        "availabilityLocalStartTimes": [
          "09:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 10
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult(s)",
            "reference": "LR1-01-new",
            "type": "YOUTH",
            "requiredContactFields": [
              "firstName"
            ],
            "restrictions": {
              "minAge": 3,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": 2,
              "maxQuantity": 7,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            }
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": false,
    "internalName": "Private Morning Tour",
    "reference": "VIP-MORN",
    "availabilityLocalStartTimes": [
      "09:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 10
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      }
    ]
  },
  "cancellable": false,
  "cancellation": {
    "refund": "text",
    "utcCancelledAt": "2021-10-27T23:38:43Z"
  },
  "freesale": false,
  "availabilityId": "text",
  "availability": {
    "id": "2021-10-27T00:00:00-04:00",
    "localDateTimeStart": "2021-10-27T00:00:00-04:00",
    "localDateTimeEnd": "2021-10-28T00:00:00-04:00",
    "allDay": false,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "[e-mail]",
    "locales": [
      "en"
    ]
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": "text"
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33b",
      "supplierReference": "K9T7R5",
      "unitId": "youth_f6446706-885a-437c-8461-efd6d7080910",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult(s)",
        "reference": "LR1-01-new",
        "type": "YOUTH",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minAge": 3,
          "maxAge": 17,
          "idRequired": false,
          "minQuantity": 2,
          "maxQuantity": 7,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        }
      },
      "status": "CONFIRMED",
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "[e-mail]",
        "locales": [
          "en"
        ]
      },
      "ticket": {
        "redemptionMethod": "DIGITAL",
        "deliveryOptions": [
          {
            "deliveryFormat": "QRCODE",
            "deliveryValue": "text"
          }
        ]
      }
    }
  ]
}