# Bookings The booking process in the Mozrest API is composed of two main steps: 1. **Creating a Pending Booking**: This temporarily holds the selected timeslot, giving the customer time to fill in contact and payment details. 2. **Committing the Pending Booking**: Once the contact details and payment (if required) are submitted, the pending booking becomes a **Booking**. This section describes the full flow, including how to: - Create and commit a pending booking - Manage bookings (view, update, cancel, list) - Understand both Pending Booking and Booking object structures If the booking requires payment, please refer to the [Payments section](/bc-api/payments) for full integration details. ## Pending Booking Object This object represents a **pending booking**, created to hold a timeslot while the user fills in contact and/or payment details. If not committed in time, it expires and the slot is released. | Key | Type | Description | | --- | --- | --- | | id | String | Pending Booking ID | | holdingTime | Integer | Time (in seconds) the booking will be held | | venueMessage | String | Optional venue message for display during payment | > EXAMPLE RESPONSE: ```json { "id": "61bb23a701a5ac259b85e3f3", "holdingTime": 420, "venueMessage": null } ``` ## Booking Object This object represents a consolidated **booking**. | Key | Type | Description | | --- | --- | --- | | id | String | Booking id | | venueId | String | Venue id for booking | | bookingChannelId | String | Booking channel id where the customer placed the booking | | status | String | Booking status `[pending, declined, confirmed, canceled, no-show, completed]` | | partySize | Int | Number of people | | date | Datetime | Booking date and time in Timestamp UTC format (ie. Saturday, 16 October 2021 14:30 is 1634387400 on timestamp) | | notes | Text | User notes | | cancelActor | String | Who had canceled the booking | | cancelReason | Text | Why the booking has been canceled | | canceledAt | Datetime | When the booking has been canceled (UTC) | | bookingType | String | Id of the booking type to book | | contact[firstname] | Text | Customer's first name | | contact[lastname] | Text | Customer's last name | | contact[email] | Text | Customer's email (ie. john.doe@email.com) | | contact[telephone] | Int | Customer's telephone including country code but NO sign (ie. +44 20 7234 3456 -> 442072343456 ) | | contact[locale] | Text | Customer's language (ISO2 format) | | contact[optInConsent] | Boolean | Allow to receive marketing emails from the Venue and the Partner (default: false) | > EXAMPLE JSON: ```json { "id": "60e890aca5f07b6ee5b950b1", "venueId": "60e890aca5f07b6ee5b950b1", "bookingChannelId": "60e890aca5f07b6ee5b950b3", "partySize": 4, "status": "confirmed", "date": "2021-11-06T12:00:00+02:00", "notes": "I'm alergic to peanuts", "bookingType": "seti_1Mw0nDEX15g1bGLpsajo6bDE", "cancelActor": null, "cancelReason": null, "canceledAt": null, "contact": { "id": "60e890aca5f07b6ee5b950b1", "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44344223322", "locale": "en", "optInConsent": true } } ``` ## Create Pending Booking A pending booking represents a booking during the online reservation process. It holds the seats during the booking process, allowing time to complete contact and payment steps. The pending booking expires after a limited time defined by the Reservation System. > EXAMPLE REQUEST: ```shell curl POST "https://api-sandbox.mozrest.com/v1/bc/pending-booking" \ -H "Authorization: Bearer {{api_key}}" \ --data-raw '{ "venueId": "619decd55bf9cb36aaa00dd6", "partySize": 4, "date": 1642339800, "areaId": "619decd55bf9cb36aaa00dd6", "bookingType": "64ca5f2cab23a4112a7d2dde", }' ``` > EXAMPLE RESPONSE: ```json { "id": "61bb23a701a5ac259b85e3f3", "holdingTime": 420, "venueMessage": null } ``` **HTTP Request:** `POST /v1/bc/pending-booking` **Parameters:** | Parameter | Status | Description | | --- | --- | --- | | venueId | Mandatory | Venue ID | | partySize | Mandatory | Number of persons | | date | Mandatory | Timestamp UTC (e.g., 1634387400) | | areaId | Optional | Area ID to book in | | bookingType | Optional | Booking type ID | ## Commit Pending Booking This endpoint allows to commit a Pending Booking. After a Pending Booking is committed it becomes a Booking and on the response a Booking with a Booking id is returned. > EXAMPLE REQUEST: ```shell curl PUT "https://api-sandbox.mozrest.com/v1/bc/pending-booking/61bb23a701a5ac259b85e3f3" \ -H "Authorization: Bearer {{api_key}}" \ --data-raw '{ "notes": "Customer notes or requests", "contact": { "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44646673377", "locale": "en", "address": { "country": "GB", "city": "London", "region": "London", "address": "Picadilly Sq. 15", "postalCode": "W1J 9LL" }, "optInConsent": "true" }' ``` > EXAMPLE JSON: ```json { "id": "61bb24011271104c686f4db5", "venueId": "619decd55bf9cb36aaa00dd6", "partySize": 4, "session": "dinner", "status": "confirmed", "date": "2022-01-16T13:30:00Z", "notes": "Customer notes or requests", "cancelActor": null, "cancelReason": null, "canceledAt": null, "bookingType" : "64ca5f2cab23a4112a7d2dde", "contact": { "id": "61b78753b419978323e22aa3", "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44646673377", "locale": "en", "optInConsent": true } } ``` **HTTP Request** `PUT https://api-sandbox.mozrest.com/v1/bc/pending-booking/{id}` **Query Parameters** | Parameter | Status | Description | | --- | --- | --- | | notes | **Optional** | User notes | | contact[firstname] | **Mandatory** | Contact's firstname | | contact[lastname] | **Mandatory** | Contact's lastname | | contact[email] | **Mandatory** | Contact's email | | contact[telephone] | **Optional** | Contact's telephone (including country code but NO sign) | | contact[locale] | **Mandatory** | Contact's language ([ISO2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format) | | contact[optInConsent] | **Optional** | Allow to get marketing emails and reminders (default: false) | ## Update Booking This endpoint allows to amend a pending status booking. > EXAMPLE REQUEST: ```shell curl PUT "https://api-sandbox.mozrest.com/v1/bc/booking/{id}" \ -H "Authorization: Bearer {{api_key}}" \ --data-raw '{ "partySize": 4, "date": 1634401800 }' ``` > EXAMPLE JSON: ```json { "id": "60e890aca5f07b6ee5b950b1", "venueId": "60e890aca5f07b6ee5b950b1", "partySize": 4, "status": "confirmed", "date": "2021-11-07T12:00:00+02:00", "notes": "I'm alergic to peanuts and broccoli", "contact": { "id": "60e890aca5f07b6ee5b950b1", "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44344223322", "locale": "en", "optInConsent": true } } ``` **HTTP Request** `PUT https://api-sandbox.mozrest.com/v1/bc/booking/{id}` **Query Parameters** | Parameter | Status | Description | | --- | --- | --- | | id | **Mandatory** | Booking id to amend | | partySize | **Mandatory** | Number of persons | | date | **Mandatory** | Date time in Timestamp UTC format (ie. Saturday, 16 October 2021 14:30 is **1634387400** on timestamp) | ## Cancel Booking This endpoint allows to cancel a booking. > EXAMPLE REQUEST: ```shell curl PUT "https://api-sandbox.mozrest.com/v1/bc/booking/{id}" \ -H "Authorization: Bearer {{api_key}}" \ --data-raw '{ "cancelActor": "me" }' ``` > EXAMPLE JSON: ```json { "id": "60e890aca5f07b6ee5b950b1", "venueId": "60e890aca5f07b6ee5b950b1", "partySize": 4, "status": "canceled", "date": "2021-11-07T12:00:00+02:00", "notes": "I'm alergic to peanuts and broccoli", "cancelActor": "user", "canceledAt": "2021-10-20T12:00:00+02:00", "contact": { "id": "60e890aca5f07b6ee5b950b1", "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44344223322", "locale": "en", "optInConsent": true } } ``` **HTTP Request** `PUT https://api-sandbox.mozrest.com/v1/bc/booking/{id}/cancel` **Query Parameters** | Parameter | Status | Description | | --- | --- | --- | | id | **Mandatory** | Booking id to cancel | | cancelActor | **Mandatory** | Who had canceled the booking | ## Get a specific booking This endpoint allows to get a specific booking. > EXAMPLE REQUEST: ```shell curl GET "https://api-sandbox.mozrest.com/v1/bc/booking/{id}" \ -H "Authorization: Bearer {{api_key}}" ``` > EXAMPLE JSON: ```json { "id": "60e890aca5f07b6ee5b950b1", "venueId": "60e890aca5f07b6ee5b950b1", "partySize": 4, "status": "confirmed", "date": "2021-11-07T12:00:00+02:00", "notes": "I'm alergic to peanuts and broccoli", "bookingType" : "64ca5f2cab23a4112a7d2dde", "contact": { "id": "60e890aca5f07b6ee5b950b1", "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44344223322", "locale": "en", "optInConsent": true } } ``` **HTTP Request** `GET https://api-sandbox.mozrest.com/v1/bc/booking/{id}` **Query Parameters** | Parameter | Status | Description | | --- | --- | --- | | id | **Mandatory** | Booking id to retrieve | ## Get a list of bookings This endpoint allows to retrieve a list of bookings. > EXAMPLE REQUEST: ```shell curl GET "https://api-sandbox.mozrest.com/v1/bc/booking" \ -H "Authorization: Bearer {{api_key}}" \ -d "offset=0" \ -d "limit=10" \ -d "email='john.doe@gmail.com'" \ -d "venueId='60e5a3ed409541da3650bd90'" \ -d "date='2021-10-24'" \ ``` > EXAMPLE JSON: ```json { "total": 16, "data": [ { "id": "60e890aca5f07b6ee5b950b1", "venueId": "60e890aca5f07b6ee5b950b1", "partySize": 4, "status": "confirmed", "date": "2021-11-07T12:00:00+02:00", "notes": "I'm alergic to peanuts and broccoli", "bookingType" : "64ca5f2cab23a4112a7d2dde", "contact": { "id": "60e890aca5f07b6ee5b950b1", "firstname": "John", "lastname": "Doe", "email": "john.doe@gmail.com", "telephone": "44344223322", "locale": "en", "optInConsent": true } } ] } ``` **HTTP Request** `GET https://api-sandbox.mozrest.com/v1/bc/booking/{id}` **Query Parameters** | Parameter | Status | Description | | --- | --- | --- | | email | **Optional** | User email that owns the booking | | venueId | **Optional** | Venue id where the booking takes place | | date | **Optional** | Date of the booking (format 2021-10-24) | At least one of the above parameters must be provided.