Resorts API: Understanding Booking Statuses and Policies

This article covers the booking lifecycle, status transitions, property policies, mandatory fees, and common error scenarios in the Resorts API v2. Understanding these concepts is essential for building a robust integration.

Booking Status Lifecycle

Every resort booking moves through a series of statuses. The diagram below shows the possible transitions:

                  ┌──────────┐
                  │   HOLD   │
                  └────┬─────┘
                       │
            ┌──────────┼──────────┐
            ▼                     ▼
    ┌──────────────┐      ┌──────────────┐
    │  CONFIRMED   │      │   RELEASED   │
    └──────────────┘      └──────────────┘

Status Definitions

Status Details

HOLD

• Created when you call the POST /itineraries endpoint.
• The room is temporarily reserved for the guest.
• You must either confirm or release the hold within the allowed time window.
• If a hold is not acted upon, it may expire automatically.

CONFIRMED

• The booking is finalized and active.
• A booking enters this state either:

• This is a terminal state — confirmed bookings cannot be released through the itineraries endpoint.

RELEASED

• The hold was explicitly released via PUT /itineraries?status=RELEASE.
• The room is no longer reserved and is available to other guests.
• This is a terminal state — released bookings cannot be reinstated.
• To rebook, the guest must go through the full search-to-booking flow again.

Important: Immediate Confirmation

Not all bookings go through a hold state. Some bookings are confirmed immediately when you call POST /itineraries. Your integration must check the status field in the response and handle both scenarios:

// Scenario 1: Hold created
{ "reference_number": "XRN-001", "status": "HOLD" }
// Scenario 2: Immediately confirmed
{ "reference_number": "XRN-002", "status": "CONFIRMED" }

If the status is CONFIRMED, do not attempt to call the confirm endpoint — the booking is already finalized.

Property Policies and Mandatory Fees

When you retrieve booking details, the response includes an urgentinfo section under propertydetails. This contains critical policy information that must be communicated to the guest.

Mandatory Fees

Mandatory fees are charges collected at the property that are not included in the booking rate. These are in addition to the total_rate paid at the time of booking.

"mandatory_fees": [
  {
    "description": "Resort fee",
    "amount": 25.00,
    "currency": "USD",
    "frequency": "per night"
  },
  {
    "description": "Parking fee",
    "amount": 15.00,
    "currency": "USD",
    "frequency": "per night"
  }
]

Best practice: Calculate and display the total mandatory fees for the full stay alongside the booking rate so guests understand the complete cost. For example: "Resort fee: $25.00/night x 6 nights = $150.00 due at check-in."

Policy Restrictions

Policy restrictions define the property's rules and requirements.

"policy_restrictions": {
  "pets": "No pets allowed.",
  "smoking": "Non-smoking property. Smoking is prohibited in all rooms and common areas.",
  "minimum_age": 21,
  "resort_fees": "A mandatory resort fee of $25.00 per night is charged at check-in. This fee covers pool access, Wi-Fi, and fitness center."
}

Best practice: Display policy restrictions at two key points:

1. Before booking — Show policies on the property detail or booking confirmation page so guests can make an informed decision.
2. After booking — Include policies in the booking confirmation email and pre-arrival communications.

Error Reference

Below is a summary of common errors you may encounter across the booking lifecycle.

400 — Bad Request

{
  "message": "Total rate does not match the confirmed price",
  "status": 400
}

404 — Not Found

{
  "message": "No results found",
  "status": 404
}

417 — Expectation Failed

{
  "message": "Booking is not in HOLD state",
  "status": 417
}

Integration Checklist

Use this checklist to verify your Resorts API integration handles all key scenarios:

• [ ] Autocomplete returns results and region codes are stored correctly.
• [ ] Property search sends the region code, dates, and coordinates.
• [ ] Filters and sorting are applied correctly and handle empty result sets.
• [ ] Property details and facility data are retrieved and cached appropriately.
• [ ] Availability check stores the room token for the selected room.
• [ ] Pricing confirmation uses the confirmed totalRate (camelCase) for the booking.
• [ ] Hold creation passes the correct totalrate, token, and recommendationid.
• [ ] Both booking statuses (HOLD and CONFIRMED) are handled from the hold endpoint.
• [ ] Confirm hold is called only when the initial status is HOLD.
• [ ] Release hold is available for bookings in HOLD state.
• [ ] Booking retrieval displays all details including urgent_info.
• [ ] Mandatory fees are calculated and shown clearly to the guest.
• [ ] Policy restrictions are surfaced before and after booking.
• [ ] Error responses (400, 404, 417) are handled gracefully with user-friendly messages.

This is the final article in the Resorts API series. For questions or support, contact customersupport@xeni.com.