# API Booking options This guide provides an extended explanation of how to use booking options. BeMyGuest booking options infographic: ![Booking Options Infographic](https://res.cloudinary.com/apimatic/image/upload/v1714982509/5728220825fb33da38fc63c3/5728220825fb33da38fc63c3--booking_options_infographic.png) [Download as PDF](https://bemyguest.com.sg/images/apidocs/booking_options_infographic.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. ```json { "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` ```json { "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` ```json { "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` ```json { "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). ```json { "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 } ] ] } } ```