Managing Bookings: Status, Retrieval & Cancellation

After a booking is created, you can retrieve its details and process cancellations through the Xeni Hotels API. This article covers the booking management endpoints and the booking statuses you'll encounter.

Retrieve Booking Details

Endpoint

GET /hotels/api/v2/bookings/{booking_id}

Path Parameters

Headers

Example Request

GET /hotels/api/v2/bookings/XENI-1700000000-ABC123DEFAuthorization: {signature}x-correlation-id: {correlation_id}Content-Type: application/json

Example Response

{
  "data": {
    "booking_id": "XENI-1700000000-ABC123DEF",
    "confirmation_number": "HTL-98765",
    "booking_status": "confirmed",
    "property": {
      "property_id": "XN00012345",
      "name": "Oceanview Resort & Spa"
    },
    "guest": {
      "title": "Mr",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone": {
        "country_code": "1",
        "number": "5551234567"
      }
    },
    "room": {
      "name": "Deluxe Ocean View King",
      "check_in": "2025-06-01",
      "check_out": "2025-06-05"
    },
    "pricing": {
      "total_price": 891.08,
      "base_price": 756,
      "taxes": 95.08,
      "fees": 40,
      "currency": "USD"
    },
    "cancellation_policy": "Free cancellation until 48 hours before check-in.",
    "created_at": "2025-05-20T14:30:00Z"
  }
}

*

Note: For full details on creating bookings (direct API and SSO checkout), see Booking Hotels — Direct API & SSO Checkout.

*

Cancel a Booking

Endpoint

PATCH /hotels/api/v2/bookings/{booking_id}

Request Body

Example Request

PATCH /hotels/api/v2/bookings/XENI-1700000000-ABC123DEFAuthorization: {signature}x-correlation-id: {correlation_id}Content-Type: application/json
{  "booking_status": "CANCELLED"}

Example Response

{
  "status": "success",
  "message": "Booking cancelled successfully",
  "data": {
    "booking_id": "XENI-1700000000-ABC123DEF",
    "booking_status": "CANCELLED"
  }
}

Important: Cancellation fees may apply depending on the rate's cancellation policy. Always check the cancellation_policy and refundable fields from the availability response before cancelling. Non-refundable bookings may not be eligible for cancellation, or may incur a full charge.

*

Booking Statuses

The booking_status field indicates the current state of a booking:

*

Booking ID Format

When creating bookings via the direct API, you supply your own booking_id. We recommend a format that includes:

• A recognizable prefix (e.g., XENI-)
• A timestamp or sequential identifier
• A random suffix for uniqueness

Example

XENI-1700000000-ABC123DEF

The API will also return a confirmation_number — this is a separate identifier generated by the hotel or supplier, and may be needed for check-in.

*

Best Practices

• Store both IDs: Save both the bookingid and the confirmationnumber. The booking ID is for API lookups; the confirmation number may be needed at the hotel.
• Check cancellation policy before booking: Display the cancellation terms to the guest during the booking flow. This sets expectations and reduces disputes.
• Handle lookup failures gracefully: If a booking isn't found by ID, it may be because the session or correlation ID has expired. Prompt the user to verify the booking ID.
• Keep a local record: For audit and support purposes, persist booking details in your own database alongside the Xeni booking data.