# Booking The steps to making a booking are as follows: 1. **Check Availability** Check the availability in the previous section and retrieve an availability ID. 2. **Booking Reservation** Create a booking that reserves the availability while you collect payment and contact information from the customer. 3. **Booking Confirmation** The final step, once payment has been taken and you want to finalize the booking. ## Booking Reservation `POST` `https://octo.peek.com/integrations/octo/bookings` The first step is to reserve the availability by creating the booking. #### Request Body | Name | Type | Description | | ----------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | uuid | String | A unique UUID to identify the booking. Setting this value acts as an idempotency key, preventing you from double booking | | expirationMinutes | Integer | How many minutes to reserve the availability, otherwise defaults to the supplier default amount | | productId\* | String | The product id | | optionId | String | The option id | | availabilityId\* | String | The availability ID | | unitItems\* | Array | An array of unit items | | unitItems\[].unitId\* | String | The unit item unit ID | | unitItems\[].uuid | String | A unique UUID to identify the unit, same as the booking uuid except per unit | | resellerReference | String | Your reference for this booking. Also known as a Voucher Number | | contact | Object | Contact information | {% tabs %} {% tab title="200: OK " %} ```javascript { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": null, "supplierReference": "X749G9", "status": "ON_HOLD", "utcExpiresAt": "2020-06-07T17:06:37Z", "utcConfirmedAt": null, "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": null, "freesale": false, "notes": "optional notes on the booking", "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-08:00", "localDateTimeEnd": "2020-07-02T02:30:00-08:00", "allDay": true, "openingHours": [] }, "contact": { "fullName": null, "emailAddress": null, "phoneNumber": null, "locales": [], "country": null }, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" } ] } ``` {% endtab %} {% endtabs %} The request above was made with the following request body: ```javascript { "productId": "av_123", "optionId": "av_123", "availabilityId": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "notes": "Optional notes for the booking", "unitItems": [ { "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" } ] } ``` The UUID on the request body and on each unit is optional but recommended if you're requesting from a source of poor network connectivity. If the connection fails or you do not receive a response, you can repeat the same request with the same UUID and it will respond with the same booking object without duplicating the booking. The booking object is described as: | Field | Description | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uuid` | A unique UUID used to identify booking. Make sure you save this value as you will need it to perform any future actions against this booking. | | `testMode` | Whether this booking is in test mode. | | `resellerReference` | Your reference (as the reseller). You set this value in the second confirmation request | | `supplierReference` | The Peek Pro reference for this booking. Use this to help the supplier find this booking. | | `status` |

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.

| | `utcExpiresAt` | An ISO8601 date time in UTC for when this booking is due to expire if the status is `ON_HOLD` | | `utcConfirmedAt` | An ISO8601 date time in UTC when the booking was confirmed. | | `productId` | The product ID for this booking | | `optionId` | The option ID for this booking | | `cancellable` | A boolean field indicating whether this booking can be cancelled. | | `cancellation` | An object with information about why and when the booking was cancelled. This is `null` if the booking is not cancelled. | | `freesale` | Whether the booking was made as freesale (without checking availability first). | | `notes` | Public notes on the booking. | | `cancellation.reason` | A text value describing why the cancellation happened. | | `cancellation.refund` | Whether the booking was refunded as part of the cancellation. Possible values are `FULL`, `PARTIAL` or `NONE` | | `cancellation.utcCancelledAt` | An ISO8601 date time in UTC indicating when the booking was cancelled. | | `availability` | The availability object that was booked. | | `availability.id` | The availability id that was used in the request. | | `availability.localDateTimeStart` | The `localDateTimeStart` value from the original availability object. | | `availability.localDateTimeEnd` | The `localDateTimeEnd` value from the original availability object. | | `availability.allDay` | A boolean value indicating whether the availability is all day. | | `availability.openingHours` | The opening hours from the original availability object. | | `contact` | The customer contact details. These values are set in the booking confirmation step. | | `contact.fullName` | The full name of the guest | |

contact.emailAddress

| The email of the guest | | `contact.phoneNumber` | The phone number of the guest | | `contact.locales` | An array of locale values, equivalent to `navigator.languages` in a browsers environment. | | `deliveryMethods` |

An array of delivery methods available for this booking. Possible values are:

VOUCHER The voucher object is populated which is a single ticket for the whole booking.

TICKET The ticket object is populated on each unit item which is a ticket for each individual person.

| | `voucher` | This value will be set if `deliveryMethods` array has `VOUCHER` as one of the values. | | `voucher.redemptionMethod` |

How the voucher can be redeemed. Possible values are:

MANIFEST The guest name will be written down and they just need to show up

DIGITAL The tickets/voucher must be scanned but can be on mobile

PRINT The tickets/voucher must be printed and presented on arrival

| | `voucher.utcRdeemedAt` | The ISO8601 date in UTC indicating when the voucher was used at the attraction. | | `voucher.deliveryOptions` | This is an array of delivery options for the voucher each object. You should use one of these to give the tickets to the guest. | | `voucher.deliveryOptions[].deliveryFormat` |

The format for the delivery option possible values are:

QRCODE You should generate the QR Code yourself on a ticket.

PDF\_URL Where you use the Peek Pro generated tickets as a PDF.

| | `voucher.deliveryOptions[].deliveryValue` |

Depending on the value of deliveryFormat this value is either:

QRCODE This value is a string to encode in a QR Code.

PDF\_URL This value is a URL linking to a Peek-generated voucher PDF.

| | `unitItems` | This is an array of unit items generated when making the booking. | | `unitItems[].uuid` | A unique UUID per unit item that you can use to help track it. | | `unitItems[].resellerReference` | Your reference (as a reseller) for this unit item. | | `unitItems[].supplierReference` | The Peek Pro reference for this unit item. | | `unitItems[].unitId` | The unit id used for this unit item | | `unitItems[].ticket` | If `deliveryMethods` has `TICKET` as one of its values this object will be set. The data structure will be identical to the `voucher` object. | The booking object schema described above will be returned on every endpoint in this section. Only the values may change. ## Booking Update `PATCH` `https://octo.peek.com/integrations/octo/bookings/:uuid` This endpoint allows you to update an existing booking. The request parameters are the same as the booking reservation endpoint. {% tabs %} {% tab title="200: OK " %} ```javascript { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": null, "supplierReference": "X749G9", "status": "ON_HOLD", "utcExpiresAt": "2020-06-07T17:06:37Z", "utcConfirmedAt": null, "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": null, "freesale": false, "notes": "optional notes on the booking", "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-05:00", "localDateTimeEnd": "2020-07-02T02:30:00-05:00", "allDay": true, "openingHours": [] }, "contact": { "fullName": null, "emailAddress": null, "phoneNumber": null, "locales": [], "country": null }, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" } ] } ``` {% endtab %} {% endtabs %} You can update 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.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. ## Booking Confirmation `POST` `https://octo.peek.com/integrations/octo/bookings/:uuid/confirm` This endpoint confirms the booking so it's ready to be used. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ----------------------- | | uuid\* | String | The UUID of the booking | #### Request Body | Name | Type | Description | | ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------- | | resellerReference | String | Your reference for this booking. Also known as a Voucher Number. | | contact\* | Object | Contact information | | contact.fullName\* | String | The customer's full name | | contact.emailAddress\* | String | The customer's email | | contact.phoneNumber | String | The customer's phone number | | contact.locales | Array | An array of customer's locales. You can get this from `navigator.languages` in a browser context. | | contact.country | String | The customer's country code | {% tabs %} {% tab title="200: OK " %} ```javascript { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": "VOUCHER-0123", "supplierReference": "X749G9", "status": "CONFIRMED", "utcExpiresAt": null, "utcConfirmedAt": "2020-06-07T18:36:29Z", "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": null, "freesale": false, "notes": "Optional notes on the booking", "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-08:00", "localDateTimeEnd": "2020-07-02T02:30:00-08:00", "allDay": true, "openingHours": [] }, "contact": { "fullName": "Oliver Morgan", "emailAddress": "ollym@me.com", "phoneNumber": "+447840739436" }, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [ { "deliveryFormat": "QRCODE", "deliveryValue": "http://short.peek.stack/public-html/app-redirect/booking/b_qw47z/pos/" } ] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" } ] } ``` {% endtab %} {% endtabs %} An example of the confirmation request above looks like this: ```javascript { "resellerReference": "VOUCHER-0123", "contact": { "fullName": "Oliver Morgan", "emailAddress": "ollym@me.com", "phoneNumber": "+447840739436" } } ``` Once the booking is confirmed, the delivery options of both the voucher and/or ticket are populated. An example of the values is shown below: ```javascript //...inside either "voucher" and/or "ticket" "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [ { "deliveryFormat": "QRCODE", "deliveryValue": "http://short.peek.stack/public-html/app-redirect/booking/b_qw47z/pos/" } ] ``` If `booking.deliveryMethods` contains both TICKET and VOUCHER then both those values will be set. You can then offer the guest whether they'd like their tickets per-person (`booking.unitItems[].ticket`) or one for the whole booking (`booking.voucher`). If you're unable to offer the choice then it's suggested you default to one falling back to the other if that's not available. ## Booking Cancellation `POST` `https://octo.peek.com/integrations/octo/bookings/:uuid/cancel` If the booking is confirmed this endpoint will cancel it, otherwise it will release the availability that was put on hold. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ----------------------- | | uuid\* | String | The UUID of the booking | #### Request Body | Name | Type | Description | | ------ | ------ | ------------------------------------- | | reason | String | The reason for cancelling the booking | {% tabs %} {% tab title="200: OK " %} ```javascript { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": "VOUCHER-0123", "supplierReference": "X749G9", "status": "CANCELLED", "utcExpiresAt": null, "utcConfirmedAt": "2020-06-07T18:36:29Z", "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": { "refund": "FULL", "reason": "Customer requested", "utcCancelledAt": "2020-06-07T18:36:29Z" }, "freesale": false, "notes": "Optional notes on the booking", "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-08:00", "localDateTimeEnd": "2020-07-02T02:30:00-08:00", "allDay": true, "openingHours": [] }, "contact": { "fullName": "Oliver Morgan", "emailAddress": "ollym@me.com", "phoneNumber": "+447840739436" }, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [ { "deliveryFormat": "QRCODE", "deliveryValue": "http://short.peek.stack/public-html/app-redirect/booking/b_qw47z/pos/" } ] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" } ] } ``` {% endtab %} {% endtabs %} Note you can only cancel a booking if `booking.cancellable` is true. ## Extend Reservation `POST` `https://octo.peek.com/integrations/octo/bookings/:uuid/extend` Use this method to hold the availability for a booking longer if the status is \`ON\_HOLD\`. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ---------------------------- | | uuid\* | String | UUID of the original booking | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------- | ----------------------------------------------------------------------- | | expirationMinutes\* | Integer | How many minutes from now do you want to have the booking reserved for. | {% tabs %} {% tab title="200: OK " %} ```javascript { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": null, "supplierReference": "X749G9", "status": "ON_HOLD", "utcExpiresAt": "2020-06-07T17:06:37Z", "utcConfirmedAt": null, "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": null, "freesale": false, "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-08:00", "localDateTimeEnd": "2020-07-02T02:30:00-08:00", "allDay": true, "openingHours": [] }, "contact": null, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" } ] } ``` {% endtab %} {% endtabs %} ## Get Booking `POST` `https://octo.peek.com/integrations/octo/bookings/:uuid` Fetch the status of an existing booking #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | -------------------------------- | | uuid\* | String | The uuid of the original booking | {% tabs %} {% tab title="200: OK " %} ```javascript { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": "VOUCHER-0123", "supplierReference": "X749G9", "status": "CONFIRMED", "utcExpiresAt": null, "utcConfirmedAt": "2020-06-07T18:36:29Z", "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": null, "freesale": false, "notes": "Optional notes on the booking", "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-08:00", "localDateTimeEnd": "2020-07-02T02:30:00-08:00", "allDay": true, "openingHours": [] }, "contact": { "fullName": "Oliver Morgan", "emailAddress": "ollym@me.com", "phoneNumber": "+447840739436" }, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [ { "deliveryFormat": "QRCODE", "deliveryValue": "http://short.peek.stack/public-html/app-redirect/booking/b_qw47z/pos/" } ] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" } ] } ``` {% endtab %} {% endtabs %} This endpoint will fetch the booking with the provided UUID from the system. ## List Bookings `GET` `https://octo.peek.com/integrations/octo/bookings` List bookings in the system given certain parameters #### Query Parameters | Name | Type | Description | | ----------------- | ------ | -------------------------------------- | | resellerReference | String | The reseller reference on the booking | | supplierReference | String | The reference provided by the supplier | | localDate | String | All bookings made for a specific date | | localDateStart | String | First date of a date range search | | localDateEnd | String | Last date of a date range search | | productId | String | The product id to filter by | | optionId | String | The option id to filter by | {% tabs %} {% tab title="200: OK " %} ```javascript [ { "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2", "testMode": true, "resellerReference": "VOUCHER-0123", "supplierReference": "X749G9", "status": "CONFIRMED", "utcExpiresAt": null, "utcConfirmedAt": "2020-06-07T18:36:29Z", "productId": "av_123", "optionId": "av_123", "cancellable": true, "cancellation": null, "freesale": false, "notes": "Optional notes on the booking", "availability": { "id": "20200701143000_720_5214a9d6-5271-4958-a306-14a07e4084c6", "localDateTimeStart": "2020-07-01T14:30:00-08:00", "localDateTimeEnd": "2020-07-02T02:30:00-08:00", "allDay": true, "openingHours": [] }, "contact": { "fullName": "Oliver Morgan", "emailAddress": "ollym@me.com", "phoneNumber": "+447840739436" }, "deliveryMethods": [ "VOUCHER" ], "voucher": { "redemptionMethod": "DIGITAL", "utcRedeemedAt": null, "deliveryOptions": [ { "deliveryFormat": "QRCODE", "deliveryValue": "http://short.peek.stack/public-html/app-redirect/booking/b_qw47z/pos/" } ] }, "unitItems": [ { "uuid": "eeddd74e-88e6-4dab-84e9-14f7af18935f", "resellerReference": null, "supplierReference": "408H44", "unitId": "480d0c3e-80a1-4bf2-a39b-aa06332739df" }, { "uuid": "ec1e2622-1359-437b-83f8-15182759d605", "resellerReference": null, "supplierReference": "BSDYM4", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" }, { "uuid": "de9855fd-8176-4551-9ba9-ae8c997cb2bb", "resellerReference": null, "supplierReference": "E5K92G", "unitId": "ecbdb23e-9840-4d15-b6f4-254a9ea401b2" } ] }, //... other bookings ] ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://octodocs.peek.com/booking-flow/booking.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.