How to Hold and Confirm a Resort Booking

The Resorts API uses a two-step booking process: first you create a hold on the reservation, then you confirm it. This gives you a window to finalize payment or perform additional validation before the booking is committed.

Step 1: Create a Hold

Endpoint

POST {{apihost}}/resorts/api/v2/itineraries?token={token}&recommendationid={recommendation_id}

Required Headers

Query Parameters

Request Body

{
  "property_id": "RST-98765",
  "checkin": "2026-04-01",
  "checkout": "2026-04-07",
  "total_rate": 1710,
  "currency": "USD",
  "action": "CONFIRM",
  "communication_details": {
    "email": "guest@example.com",
    "phone": "+1-555-123-4567"
  },
  "traveler": {
    "first_name": "Jane",
    "middle_name": "",
    "last_name": "Doe",
    "address": "456 Palm Avenue",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90001",
    "country": "US",
    "email": "guest@example.com",
    "phone": "+1-555-123-4567"
  }
}

Request Body Fields

Example Response — Hold Created

{
  "status": 200,
  "data": {
    "reference_number": "XRN-2026040100123",
    "status": "HOLD"
  }
}

Example Response — Booking Confirmed Immediately

In some cases, the booking may be confirmed immediately without going through a hold state:

{
  "status": 200,
  "data": {
    "reference_number": "XRN-2026040100123",
    "status": "CONFIRMED"
  }
}

Error: Rate Mismatch

If the total_rate in your request does not match the confirmed pricing, the API returns a 400 error:

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

Always use the totalRate value from the pricing confirmation endpoint to avoid this error.

Step 2: Confirm the Hold

If the booking was created with a "HOLD" status, you must explicitly confirm it to finalize the reservation.

Endpoint

PUT {{apihost}}/resorts/api/v2/itineraries?referencenumber={reference_number}&status=CONFIRM

Required Headers

Query Parameters

Request Body

The request body should be empty.

Example Response

{
  "status": 200,
  "data": {
    "reference_number": "XRN-2026040100123",
    "status": "CONFIRMED"
  }
}

Error: Invalid Hold State

If the booking is not currently in a HOLD state (for example, it has already been confirmed or released), the API returns a 417 error:

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

Complete Booking Flow

Here is the full sequence from search to confirmed booking:

1. Autocomplete — Get the region code for the destination.
2. Property Search — Find available resorts and get a recommendation_id.
3. Availability — Check room availability and get a token.
4. Price — Confirm the final rate using the token and recommendation_id.
5. Hold — Create a hold with the confirmed total_rate, token, and traveler details.
6. Confirm — If the response status is "HOLD", confirm the booking to finalize it.

Best Practices

• Always confirm pricing first — Never create a hold using rates from the search or availability response. Always use the rate returned by the pricing endpoint.
• Handle both statuses — Your integration should handle both "HOLD" and "CONFIRMED" responses from the hold endpoint. If the status is "CONFIRMED", no further action is needed.
• Confirm promptly — Holds are time-limited. Confirm the booking as soon as your payment or validation process is complete.
• Store the reference number — The reference_number is your primary identifier for all subsequent operations (confirm, release, retrieve).