Hotel Bookings

The HotelBooking service manages the complete hotel booking process, from initial search to final confirmation.

Authentication | Authorization

It follows standard UBIO authentication and authorization process, please refer to here for more details.

Common Response Codes

200 OK - Request successful
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing authentication
403 Forbidden - Valid authentication but insufficient permissions
404 Not Found - Resource not found
500 Server Error - Internal server error

Booking States

A booking can have the following states (BookingState):

Started: The booking has been initiated
Pending: The booking is in progress or awaiting some inputs
Finished: The booking has been completed either successfully or unsuccessfully

Booking Stages

During the process, a booking goes through different stages (BookingStage):

PriceCheck: Initial price verification where you get available rooms and rates
RoomSelection: Room selection phase where you can if required select a specific room from the available rooms
StartBooking: Beginning of booking process where it is actually executed the process of booking the room based on initial arguments
ProcessingBooking: Processing the booking is a middle stage where it is either awaiting some inputs or processing the booking
FinalPriceConsent: Where you are required to confirm the final price of the booking
BookingConfirmation: This is the final stage reached when you hace confirmed the booking
Failed: The booking has failed

BookingStatus Object

{
  "bookingId": "uuid",
  "clientId": "string",
  "state": "Pending",
  "stage": "RoomSelection",
  "createdAt": "2024-01-01T00:00:00Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "availableRooms": [],
  "priceBreakdown": [],
  "finalPrice": null,
  "confirmation": null
}

Get Room Prices

Get initial room prices for a given search criteria

Code sample

POST/Booking/prices

curl -X POST 'https://hotels.automationcloud.net/Booking/prices' \
    -H 'Bearer <token>' \
--data '{
  "search": {
    "hotelId": "hotel123",
    "checkIn": "2024-03-01",
    "nights": 2,
    "guests": 2
  }
}'

Success Responses

Status 200

{
  "requestId": "57487287-f002-4ab7-89b4-8386f7cb1b30",
  "result": {
    "hotelId": "f77c096f-6ca2-4b91-8b18-00004ad8429e",
    "checkIn": "2025-02-15",
    "nights": 1,
    "guests": 2,
    "rooms": [
      {
        "name": "Standard Double Room",
        "capacity": 2,
        "rates": [
          {
            "name": "Advance Purchase",
            "baseRate": {
              "value": 57300,
              "currencyCode": "gbp"
            },
            "taxes": [],
            "occupancy": 2,
            "breakfastIncluded": false,
            "refundable": {
              "available": false
            },
            "rule": "default",
            "fees": [],
            "description": "Deposit Required<>Room only rate, inclusive of VAT.",
            "priceId": "c03b53345d2ee51a"
          },
          {
            "name": "Flexible Rate",
            "baseRate": {
              "value": 60000,
              "currencyCode": "gbp"
            },
            "taxes": [],
            "occupancy": 2,
            "breakfastIncluded": false,
            "refundable": {
              "available": true,
              "untilDate": "2025-02-13"
            },
            "rule": "default",
            "fees": [],
            "description": "Guaranteed with Credit Card<>Room only rate, inclusive of VAT and excluding 5% rooms service charge.",
            "priceId": "bcb202f07bb63175"
          }
        ],
        "description": "Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
        "images": [
          {
            "type": "Link",
            "name": "CRS",
            "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
          },
          {
            "type": "Link",
            "name": "VScape",
            "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
          }
        ]
      },
      "..."
    ]
  }
}

List of available rooms with prices

Confirm availability and price

Confirm if the room is available, the price is correct and return correspondings priceId's

Code sample

POST/Booking/prices/confirm

curl -X POST 'https://hotels.automationcloud.net/Booking/prices/confirm' \
    -H 'Bearer <token>' \
--data '{
  "bookingPriceId": "price123",
  "requestId": "req123",
  "simulateBooking": false
}'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "26c177b8-5233-4f17-92b4-4573ef9f9394",
  "state": "pending",
  "stage": "startBooking",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "availableRooms": [
    {
      "name": "Standard Double Room",
      "description": "Queen-size bed and cosy sitting area with walk-in shower. Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
      "images": [
        {
          "type": "Link",
          "name": "Image",
          "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
        },
        {
          "type": "Link",
          "name": "Image",
          "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
        }
      ],
      "rates": [
        {
          "name": "Advance Purchase",
          "description": "Room only rate, inclusive of VAT.",
          "baseRate": {
            "value": 54100,
            "currencyCode": "gbp"
          },
          "priceId": "92653aeb66b5c7b7",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        },
        {
          "name": "Flexible Rate",
          "description": "Room only rate, inclusive of VAT and excluding 5% rooms service charge.",
          "baseRate": {
            "value": 60000,
            "currencyCode": "gbp"
          },
          "priceId": "bcb202f07bb63175",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        }
      ]
    }
  ]
}

Room available, booking can start

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "26c177b8-5233-4f17-92b4-4573ef9f9394",
  "state": "pending",
  "stage": "roomSelection",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": {
    "category": "client",
    "code": "ClientError",
    "message": "Price not found by `bookingPriceId`. Use a different `priceId` from `availableRooms`"
  },
  "availableRooms": [
    {
      "name": "Standard Double Room",
      "description": "Queen-size bed and cosy sitting area with walk-in shower. Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
      "images": [
        {
          "type": "Link",
          "name": "Image",
          "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
        },
        {
          "type": "Link",
          "name": "Image",
          "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
        }
      ],
      "rates": [
        {
          "name": "Advance Purchase",
          "description": "Room only rate, inclusive of VAT.",
          "baseRate": {
            "value": 54100,
            "currencyCode": "gbp"
          },
          "priceId": "92653aeb66b5c7b7",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        },
        {
          "name": "Flexible Rate",
          "description": "Room only rate, inclusive of VAT and excluding 5% rooms service charge.",
          "baseRate": {
            "value": 60000,
            "currencyCode": "gbp"
          },
          "priceId": "bcb202f07bb63175",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        }
      ]
    }
  ]
}

Booking not available, needing room selection

Get Booking Status

Returns the current status of a booking by its ID.

Code sample

GET/Booking/book/{bookingId}/status

curl -X GET 'https://hotels.automationcloud.net/Booking/book/{bookingId}/status' \
    -H 'Bearer <token>'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "pending",
  "stage": "finalPriceConsent",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "finalPrice": {
    "price": {
      "value": 54100,
      "currencyCode": "gbp"
    }
  }
}

Current booking status with available information based on stage

Process Booking

Provides inputs for a booking with guest and payment information.

Code sample

POST/Booking/book/{bookingId}

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}' \
    -H 'Bearer <token>' \
--data '{
  "details": {
    "mainGuest": {
      "person": {
        "firstName": "John",
        "lastName": "Doe"
      },
      "contact": {
        "email": "john@example.com",
        "phone": "+1234567890"
      }
    }
  },
  "payment": {
    "card": {
      "type": "credit",
      "holderName": "John Doe",
      "expirationDate": "12/25"
    }
  },
  "panToken": "token123"
}'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "pending",
  "stage": "processingBooking",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null
}

Booking status after initialization

Select Room

Selects a room for the booking based on bookingPriceId. This end-point will only be used when the selected room/rate is not currently available, and a new one needs to be selected.

Code sample

POST/Booking/book/{bookingId}/select-room

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}/select-room' \
    -H 'Bearer <token>' \
--data '{
  "bookingPriceId": "price123"
}'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "pending",
  "stage": "processingBooking",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null
}

Updated booking status after room selection

Confirm Booking

Confirms the booking with the existing final price for the booking.

Code sample

POST/Booking/book/{bookingId}/confirm

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}/confirm' \
    -H 'Bearer <token>'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "finished",
  "stage": "bookingConfirmation",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": "2025-02-03T12:51:35.927Z",
  "confirmation": {
    "reservationNumber": "ABC123",
    "hotelConfirmationNumber": "XYZ789"
  }
}

Booking status with confirmation details

Cancel Booking

Cancels an active booking.

Code sample

POST/Booking/book/{bookingId}/cancel

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}/cancel' \
    -H 'Bearer <token>'

Success Responses

Status 200

{
  "bookingId": "123e4567-e89b-12d3-a456-426614174000",
  "state": "Finished",
  "stage": "Failed"
}

Updated booking status after cancellation

# Hotel Bookings

# Authentication | Authorization

# Common Response Codes

# Booking States

# Booking Stages

# BookingStatus Object

# Get Room Prices

# Code sample

# Success Responses

# Confirm availability and price

# Code sample

# Success Responses

# Get Booking Status

# Code sample

# Success Responses

# Process Booking

# Code sample

# Success Responses

# Select Room

# Code sample

# Success Responses

# Confirm Booking

# Code sample

# Success Responses

# Cancel Booking

# Code sample

# Success Responses

Hotel Bookings

Authentication | Authorization

Common Response Codes

Booking States

Booking Stages

BookingStatus Object

Get Room Prices

Code sample

Success Responses

Confirm availability and price

Code sample

Success Responses

Get Booking Status

Code sample

Success Responses

Process Booking

Code sample

Success Responses

Select Room

Code sample

Success Responses

Confirm Booking

Code sample

Success Responses

Cancel Booking

Code sample

Success Responses