Sign in
Bookings

Booking Reservation

Changed on

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.

post/bookings/

Request

  • Base URL: http://localhost:8080/api/octo
  • URL: http://localhost:8080/api/octo/bookings/
  • Auth: HTTP bearer

Headers

Octo-Capabilitiesstring required

A list of the Capabilities (their IDs) initialized with your request.

Accept-Languagestring

This optional request header allows to specify preferred languages for content in the response. A language code that specifies the language of the product content. This code must conform to the BCP 47 standard, following RFC 5646 and RFC 4647 specifications for language tags. Examples include en-US for American English, fr-FR for French (France), and es-ES for Spanish (Spain). This header supports a comma-separated list of language tags with optional quality values (q) to indicate priority, such as en-US, fr-CA;q=0.8, fr;q=0.7, which prioritizes U.S. English, followed by Canadian French, and general French. This header is defined in the HTTP/1.1 specification (RFC 7231) and is commonly used for internationalized websites and services to enhance user experience. For more details, visit MDN Web Docs: Accept-Language - HTTP | MDN. Note this only determines preference and does not guarantee location has content available in the desired language.

Request body

uuidstring uuid

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

productIdstring required

The product ID for this booking.

optionIdstring required

The option ID for this booking.

availabilityIdstring

The availability ID for the selected timeslot.

expirationMinutesinteger

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

notesstring nullable

Optional notes for the booking.

resellerReferencestring

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

currencystring nullable

Can be used only when pricing capability is used.

Example request

{
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "optionId": "DEFAULT",
  "availabilityId": "2022-05-23T00:00:00+01:00",
  "notes": "Optional notes",
  "unitItems": [
    {
      "unitId": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
    },
    {
      "unitId": "child_797e3ce8-1860-4cbf-80ad-95857df1f640"
    },
    {
      "unitId": "infant_897e3ce8-1860-4cbf-80ad-95857df1f640"
    }
  ]
}

Response

The request has succeeded.

idstring required

A unique identifier generated by the supplier system for the booking. This ID ensures traceability and must be unique within the system.

uuidstring uuid required

An optional idempotency key set when creating a booking to prevent duplicate bookings in case of retries. Used for API calls.

testModeboolean required

Indicates whether the booking was created in test mode. If true, it is a test booking.

resellerReferencestring nullable required

A reference provided by the reseller to identify the booking.

supplierReferencestring nullable required

A reference provided by the reseller to identify the booking.

status'ON_HOLD' | 'CONFIRMED' | 'EXPIRED' | 'CANCELLED' | 'REDEEMED' | 'PENDING' | 'REJECTED' required
utcCreatedAtstring date-time required

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

utcUpdatedAtstring date-time required

An ISO8601 date time in UTC when the booking was last updated, if applicable.

utcExpiresAtstring date-time nullable required

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

utcRedeemedAtstring date-time nullable required

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

utcConfirmedAtstring date-time nullable required

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

productIdstring required

The ID of product booked.

optionIdstring required

The ID of option booked.

cancellableboolean required

The object of booked option.

freesaleboolean required

Indicates if the booking was made without checking availability.

availabilityIdstring nullable required

The ID of availability booked.

notesstring nullable required

Customer-facing public notes for the booking.

deliveryMethodsDeliveryMethod[] required

Specifies all supported methods of how tickets or vouchers for this booking are delivered. TICKET: Delivered individually per unit in the booking, where each person or unit receives a separate ticket. These will be provided in the ticket object. VOUCHER: Delivered as a single voucher for the entire booking, consolidating all units under one document. These will be provided in the voucher object. This field ensures clarity on the format of ticket or voucher delivery to resellers and customers.

Example response

{
  "id": "bbbb6227-54fc-4c32-9ed7-dc3eb99966ea",
  "uuid": "559aed3d-6d5b-4fe0-bfca-99f5e7218a56",
  "supplierReference": "XOPSUT",
  "status": "CONFIRMED",
  "utcCreatedAt": "2022-05-25T10:34:22Z",
  "utcUpdatedAt": "2022-05-25T10:34:22Z",
  "utcExpiresAt": "2022-05-25T11:04:22Z",
  "utcRedeemedAt": "2022-06-25T10:34:22Z",
  "utcConfirmedAt": "2022-05-25T11:00:22Z",
  "productId": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
  "product": {
    "id": "6b903d44-dc24-4ca4-ae71-6bde6c4f4854",
    "internalName": "London Eye General Admission",
    "reference": "LEYE-GA",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "allowFreesale": true,
    "instantConfirmation": true,
    "instantDelivery": true,
    "availabilityRequired": true,
    "availabilityType": "START_TIME",
    "deliveryFormats": [
      "QRCODE"
    ],
    "deliveryMethods": [
      "TICKET"
    ],
    "redemptionMethod": "DIGITAL",
    "options": [
      {
        "id": "DEFAULT",
        "default": true,
        "internalName": "DEFAULT",
        "reference": null,
        "availabilityLocalStartTimes": [
          "00:00"
        ],
        "cancellationCutoff": "1 hour",
        "cancellationCutoffAmount": 1,
        "cancellationCutoffUnit": "hour",
        "requiredContactFields": [
          "firstName"
        ],
        "restrictions": {
          "minUnits": 0,
          "maxUnits": 9
        },
        "units": [
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Adult",
            "reference": null,
            "type": "ADULT",
            "restrictions": {
              "minAge": 18,
              "maxAge": 99,
              "idRequired": false,
              "minQuantity": 1,
              "maxQuantity": 10,
              "paxCount": 1,
              "accompaniedBy": []
            },
            "requiredContactFields": [
              "firstName"
            ]
          },
          {
            "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Child",
            "reference": null,
            "type": "CHILD",
            "restrictions": {
              "minAge": 3,
              "maxAge": 12,
              "idRequired": false,
              "minQuantity": 1,
              "maxQuantity": 10,
              "paxCount": 1,
              "accompaniedBy": []
            },
            "requiredContactFields": [
              "firstName"
            ]
          },
          {
            "id": "infant_897e3ce8-1860-4cbf-80ad-95857df1f640",
            "internalName": "Infant",
            "reference": null,
            "type": "INFANT",
            "restrictions": {
              "minAge": 0,
              "maxAge": 3,
              "idRequired": false,
              "minQuantity": 1,
              "maxQuantity": 10,
              "paxCount": 1,
              "accompaniedBy": [
                "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
              ]
            },
            "requiredContactFields": [
              "firstName"
            ]
          }
        ]
      }
    ]
  },
  "optionId": "DEFAULT",
  "option": {
    "id": "DEFAULT",
    "default": true,
    "internalName": "DEFAULT",
    "reference": null,
    "availabilityLocalStartTimes": [
      "00:00"
    ],
    "cancellationCutoff": "1 hour",
    "cancellationCutoffAmount": 1,
    "cancellationCutoffUnit": "hour",
    "requiredContactFields": [
      "firstName"
    ],
    "restrictions": {
      "minUnits": 0,
      "maxUnits": 9
    },
    "units": [
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult",
        "reference": null,
        "type": "ADULT",
        "restrictions": {
          "minAge": 18,
          "maxAge": 99,
          "idRequired": false,
          "minQuantity": 1,
          "maxQuantity": 10,
          "paxCount": 1,
          "accompaniedBy": []
        },
        "requiredContactFields": [
          "firstName"
        ]
      },
      {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Child",
        "reference": null,
        "type": "CHILD",
        "restrictions": {
          "minAge": 3,
          "maxAge": 12,
          "idRequired": false,
          "minQuantity": 1,
          "maxQuantity": 10,
          "paxCount": 1,
          "accompaniedBy": []
        },
        "requiredContactFields": [
          "firstName"
        ]
      },
      {
        "id": "infant_897e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Infant",
        "reference": null,
        "type": "INFANT",
        "restrictions": {
          "minAge": 0,
          "maxAge": 3,
          "idRequired": false,
          "minQuantity": 1,
          "maxQuantity": 10,
          "paxCount": 1,
          "accompaniedBy": [
            "adult_697e3ce8-1860-4cbf-80ad-95857df1f640"
          ]
        },
        "requiredContactFields": [
          "firstName"
        ]
      }
    ],
    "pricingFrom": [
      {
        "original": 2000,
        "retail": 2000,
        "net": 1600,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": []
      }
    ]
  },
  "cancellable": true,
  "cancellation": {
    "refund": "FULL",
    "reason": "this product sucks",
    "utcCancelledAt": "2022-05-25T11:00:22Z"
  },
  "availability": {
    "id": "2022-05-23T00:00:00+01:00",
    "localDateTimeStart": "2022-05-23T00:00:00+01:00",
    "localDateTimeEnd": "2022-05-24T00:00:00+01:00",
    "utcCutoffAt": "2022-05-22T23:00:00Z",
    "allDay": false,
    "available": true,
    "status": "AVAILABLE",
    "vacancies": 10,
    "capacity": 10,
    "maxUnits": null,
    "openingHours": [
      {
        "from": "08:00",
        "to": "16:00"
      }
    ]
  },
  "contact": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "johndoe@email.com",
    "phoneNumber": "",
    "locales": [
      "en"
    ],
    "postalCode": "",
    "country": "",
    "notes": ""
  },
  "notes": "Optional notes for the booking",
  "deliveryMethods": [
    "TICKET",
    "VOUCHER"
  ],
  "voucher": {
    "redemptionMethod": "DIGITAL",
    "utcRedeemedAt": "2021-10-27T23:28:43Z",
    "deliveryOptions": [
      {
        "deliveryFormat": "QRCODE",
        "deliveryValue": ""
      }
    ]
  },
  "unitItems": [
    {
      "uuid": "3b1bc2ee-3155-4738-9471-f49842a07327",
      "resellerReference": "4ec08a62-892c-48c1-a608-dc946531a33a",
      "supplierReference": "K9T7R4",
      "unitId": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
      "unit": {
        "id": "adult_697e3ce8-1860-4cbf-80ad-95857df1f640",
        "internalName": "Adult",
        "reference": null,
        "type": "ADULT",
        "restrictions": {
          "minAge": 18,
          "maxAge": 99,
          "idRequired": false,
          "minQuantity": 1,
          "maxQuantity": 10,
          "paxCount": 1,
          "accompaniedBy": []
        },
        "requiredContactFields": [
          "firstName"
        ]
      },
      "status": "ON_HOLD",
      "utcRedeemedAt": null,
      "contact": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "johndoe@email.com",
        "phoneNumber": "",
        "locales": [
          "en"
        ],
        "postalCode": "",
        "country": "",
        "notes": ""
      },
      "ticket": null
    }
  ],
  "pricing": {
    "original": 3995,
    "retail": 3995,
    "net": 2996,
    "currency": "USD",
    "currencyPrecision": 2,
    "includedTaxes": [
      {
        "name": "VAT 10",
        "retail": 700,
        "original": 700,
        "net": 400
      }
    ]
  }
}

Changes

  • d3140ede7e86Revision changes
    • info

      the request property ///// became nullable

    • info

      the request property ///// became nullable

    • info

      the request property ///// became nullable

    • info

      the request property ///// became nullable

    • info

      the request property ///// became nullable

    • info

      the request property ///// became nullable

    • info

      the request property ///// became nullable

    • info

      the request property /// became nullable

    • info

      the request property /// became nullable

    • info

      the request property /// became nullable

    • info

      the request property /// became nullable

    • info

      the request property /// became nullable

    • info

      the request property /// became nullable

    • info

      the request property /// became nullable

  • 1bc145e5d88cRevision changes
    • info

      the request property ///// became nullable

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      the request property /// became nullable