Custom Questions

Adds custom questions to order, booking, and unit-item flows

To use this capability, add octo/questions to your Octo-Capabilities header.

Custom questions let you collect additional guest information during booking and order flows. These questions are informational and do not change availability or pricing.

Operations below use the /octo prefix.

Question Definitions

Supported product routes:

• GET /products

• GET /products/{productId}

With this capability enabled, question definitions are added to option and unit schemas in product responses.

Questions are sorted by configured question position.

The same questions arrays are also returned on:

• booking.option.questions[]

• booking.option.units[].questions[]

• booking.unitItems[].unit.questions[]

• The same nested booking paths under order.bookings[]

Question Object Fields

inputType is derived from options:

• textarea: no options

• radio: 1-5 options

• select: more than 5 options

Question objects are returned in the product and booking/order schemas from Products, Bookings, and Multi-Booking Cart.

You should display booking-level questions once per booking, and ticket-level questions once per unit item.

Submit question answers before or on your final booking/order confirmation call so they are persisted with the confirmed records.

Submit Answers On Booking Routes

Booking question fields are supported by these booking write routes:

• POST /bookings

• PATCH /bookings/{uuid}

• POST /bookings/{uuid}/confirm

Request Body Fields

Base booking schema: Bookings.

Submit Answers On Order Routes (octo/cart Required)

To submit order-level question answers, include both capabilities in the header:

• octo/questions

• octo/cart

Order question fields are supported by:

• POST /orders

• PATCH /orders/{orderId}

• PATCH /orders/{orderId}/preview

• POST /orders/{orderId}/confirm

Returned Answer Fields

Booking objects include question answers on these routes:

• POST /bookings

• PATCH /bookings/{uuid}

• POST /bookings/{uuid}/confirm

• POST /bookings/{uuid}/extend

• POST /bookings/{uuid}/cancel

• GET /bookings

• GET /bookings/{uuid}

Order objects include question answers on these routes (octo/cart required):

• POST /orders

• PATCH /orders/{orderId}

• PATCH /orders/{orderId}/preview

• POST /orders/{orderId}/confirm

• POST /orders/{orderId}/extend

• POST /orders/{orderId}/cancel

• DELETE /orders/{orderId}

• GET /orders

• GET /orders/{orderId}

Each answer object field is included in the booking and order schemas.

Base schemas: Bookings and Multi-Booking Cart.

questionAnswers arrays are returned in question position order and include all currently valid questions for that object, plus any existing persisted answers that are still attached.

On update routes, omitting questionAnswers leaves existing answers unchanged.

To clear an existing answer, send the same questionId with value: null (or empty string) in the relevant questionAnswers array.

If a submitted questionId is unknown for that scope (order, booking, or ticket), the API returns INVALID_QUESTION_ID and includes questionId in the error body.

Recommended flow: create or fetch the booking/order first, then render your form from questionAnswers (and unitItems[].questionAnswers for unit items). Unanswered questions are returned with value: null.

Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

Booking

{
  "// ...rest of booking object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

BookingUnitItem

{
  "// ...rest of booking unit item object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

BookingUnitItemWriteRequest

{
  "// ...rest of booking unit item write request object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

BookingWriteRequest

{
  "// ...rest of booking write request object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

Option

{
  "// ...rest of option object": "...",
  "questions": [
    {
      "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
      "title": "Summer Promotion",
      "required": true,
      "inputType": "select"
    }
  ]
}

Order

{
  "// ...rest of order object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

OrderCreateRequest

{
  "// ...rest of order create request object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

OrderUpdateRequest

{
  "// ...rest of order update request object": "...",
  "questionAnswers": [
    {
      "questionId": "question_dietary_requirements",
      "value": "Vegetarian"
    }
  ]
}

Unit

{
  "// ...rest of unit object": "...",
  "questions": [
    {
      "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
      "title": "Summer Promotion",
      "required": true,
      "inputType": "select"
    }
  ]
}