Skip to content
Guides
/
Booking Options
Last updated

API Booking options

This guide provides an extended explanation of how to use booking options.

BeMyGuest booking options infographic: Booking Options Infographic

Download as PDF

Booking options are information you need to collect from a guest to process a booking. Please consider every booking option as an input field to be dynamically generated and added to the customer checkout form. There are 14 types of booking options, each with a corresponding HTML input type.

List of Booking Option Types

  • type: "1" - list (HTML input type: select)
  • type: "2" - list multiple (HTML input type: select multiple)
  • type: "3" - number (HTML input type: text with number validation)
  • type: "4" - string (HTML input type: text)
  • type: "5" - boolean (HTML input type: checkbox)
  • type: "6" - date (HTML input type: text with date validation, e.g., YYYY-MM-DD)
  • type: "7" - file (HTML input type: file)
  • type: "8" - image (HTML input type: file with image type validation)
  • type: "9" - address (HTML input type: text)
  • type: "10" - time (HTML input type: text with time validation, e.g., hh:mm)
  • type: "11" - datetime (HTML input type: text with datetime validation, e.g., YYYY-MM-DD hh:mm)
  • type: "12" - string: country (HTML input type: text)
  • type: "13" - string: phone (HTML input type: text)
  • type: "14" - string: flight no (HTML input type: text with flight number validation: ^[A-Z0-9][A-Z0-9][0-9]{0,4}$)

You can build the UI according to your own design, for example, using radio buttons instead of a select list.

Booking options are present at the product type level, but at the product level, there are two flags to mark their presence:

  • hasOptions: true if at least one product-type has booking options.
  • allProductTypesHaveOptions: true if all product-types have booking options.
{
  "hasOptions": true,
  "allProductTypesHaveOptions": true
}

Booking options can be required to make a booking. They have a key required: true/false.

Example on API demo:

  • Product UUID: d3bfa3e1-edd4-5c24-a051-4d6c56aae621
  • Product-type UUID: 9a7b8133-6654-5a8d-94f2-e5680a030fa3
{
  "options": {
    "perBooking": [
      {
        "uuid": "6587c77f-97fb-47ed-b74b-bdd9f1e99bc1",
        "name": "Flight Number",
        "nameTranslated": "Flight Number",
        "description": null,
        "descriptionTranslated": null,
        "required": true,
        "addOn": false,
        "formatRegex": null,
        "inputType": 4,
        "validFrom": null,
        "validTo": null
      },
      {
        "uuid": "e9d7f9ba-8528-4920-a4b0-632bf4cfa4f9",
        "name": "Airport Name",
        "nameTranslated": "Airport Name",
        "description": null,
        "descriptionTranslated": null,
        "required": true,
        "addOn": false,
        "formatRegex": null,
        "inputType": 4,
        "validFrom": null,
        "validTo": null
      },
      {
        "uuid": "0cbebb60-fa25-4fc1-9712-fd7b716fc9d4",
        "name": "Arrival Date/Time",
        "nameTranslated": "Arrival Date/Time",
        "description": null,
        "descriptionTranslated": null,
        "required": true,
        "addOn": false,
        "formatRegex": null,
        "inputType": 11,
        "validFrom": null,
        "validTo": null
      },
      {
        "uuid": "79c17fb7-3891-4705-98e5-c3a9459bf639",
        "name": "Drop-off Address",
        "nameTranslated": "Drop-off Address",
        "description": null,
        "descriptionTranslated": null,
        "required": true,
        "addOn": false,
        "formatRegex": null,
        "inputType": 9,
        "validFrom": null,
        "validTo": null
      }
    ],
    "perPax": []
  }
}

Key Explanation

  • uuid: The UUID of the booking option.
  • name: The name of the booking option (e.g., "Full name").
  • nameTranslated: The name of the booking option in the requested language.
  • description: A description of the booking option (e.g., "as shown on passport"). An empty string if not present.
  • descriptionTranslated: The description of the booking option in the requested language.
  • required: true or false. If true, a booking cannot be made without including this booking option in the payload.
  • addOn: true or false. If true, you should display this option on the product detail page.
  • formatRegex: Additional regex to be used for client-side validation (e.g., for a flight number: ^[A-Z0-9][A-Z0-9][0-9]{0,4}$). null when not applicable.
  • inputType: An integer defining the type of input (e.g., 4 for a string, 1 for a list).
  • validFrom: The start date if the booking option is valid for a limited time. null when not applicable. Only applicable for arrival dates greater than or equal to this date.
  • validTo: The end date if the booking option is valid for a limited time. null when not applicable. Only applicable for arrival dates less than or equal to this date.

Booking options can be perBooking and/or perPax.

  • perBooking: One option per booking request is required.
  • perPax: The option is required for every guest (adult, senior, child).

Example on API demo:

  • Product UUID: d0ac2916-698c-54ef-bd1b-6ecf273c598f
  • Product-type UUID: b7883bc7-85c9-5ad9-b52f-cabba964e1ba

Booking options can also have a price, which can be per option or per item. The booking option price needs to be added to the total price of the booking.

Example on API demo (Pricing per option):

  • Product UUID: d4398f47-9fc0-5f38-ba2d-d04a5fe8327e
  • Product-type UUID: 7b1fa020-2bac-56bc-b145-a3592493ac4f
{
  "options": {
    "perBooking": [
      {
        "uuid": "383f0b49-e7dc-4c24-9640-5ed0370533a1",
        "name": "Raincoat",
        "nameTranslated": "Raincoat",
        "description": "Good for rainy days",
        "descriptionTranslated": "Good for rainy days",
        "required": false,
        "addOn": false,
        "formatRegex": null,
        "inputType": 5,
        "validFrom": null,
        "validTo": null,
        "price": 5
      }
    ],
    "perPax": []
  }
}

Example on API demo (Pricing per item):

  • Product UUID: e8f0b93c-ee5d-54b7-8813-8004c26c658c
  • Product-type UUID: 23fa0c48-17e9-5716-8dac-4a8bb142a17f
{
  "options": {
    "perBooking": [
      {
        "uuid": "0b40932c-53e2-423d-bbf7-b12cc998342e",
        "name": "Select pickup zone",
        "nameTranslated": "Selected pickup zone",
        "description": "Zone 1: Some description where to meet.\nZone 2: Some other description where is the meeting place for this zone.",
        "descriptionTranslated": "Zone 1: Some description where to meet.\nZone 2: Some other description where is the meeting place for this zone.",
        "required": true,
        "addOn": false,
        "formatRegex": null,
        "inputType": 1,
        "validFrom": null,
        "validTo": null,
        "items": [
          {
            "label": "Zone 1 (SGD 10)",
            "labelTranslated": "Zone 1 (SGD 10)",
            "value": "Zone 1",
            "price": 10
          },
          {
            "label": "Zone 2 (SGD 5)",
            "labelTranslated": "Zone 2 (SGD 5)",
            "value": "Zone 2",
            "price": 5
          }
        ]
      }
    ],
    "perPax": []
  }
}

When POSTing a booking, perBooking options are in an array, and perPax options are in an array of arrays (one array per pax).

{
  "productTypeUuid": "4dd361a3-a964-597a-8a99-06b2a2ca9224",
  "customer": {
    "email": "some.email@domain.com",
    "firstName": "Michal",
    "lastName": "S",
    "phone": "+65 0000 0000",
    "salutation": "Mr."
  },
  "adults": 1,
  "seniors": 0,
  "children": 2,
  "arrivalDate": "2018-08-07",
  "message": null,
  "partnerReference": null,
  "timeSlotUuid": "f1cc0983-e8ed-577c-8b93-a8a7bfdbff5c",
  "options": {
    "perBooking": [
      {
        "uuid": "46db421e-5727-46fc-9f2c-10679e026582",
        "value": "1"
      },
      {
        "uuid": "46db421e-5727-46fc-9f2c-10679e026582",
        "value": "2"
      }
    ],
    "perPax": [
      [
        {
          "uuid": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246",
          "value": 5
        }
      ],
      [
        {
          "uuid": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246",
          "value": 9
        }
      ],
      [
        {
          "uuid": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246",
          "value": 30
        }
      ]
    ]
  }
}
Previous page
Next page