Stay Perks

Search 2,000+ Virtuoso hotels, plus packages, cruises and private experiences, by place, brand or kind of stay. Results show whether Virtuoso perks apply, a trip_id for get_trip_details, and how to book. No live rates: the advisor quotes them.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "description": "A city, region or country (\"Paris\", \"Tuscany\", \"Caribbean\"), a hotel or brand (\"Four Seasons\"), both (\"Four Seasons Paris\"), or a kind of stay (\"beach\", \"safari\")"
    },
    "check_in": {
      "type": "string",
      "description": "Check-in date (ISO 8601)"
    },
    "check_out": {
      "type": "string",
      "description": "Check-out date (ISO 8601)"
    },
    "budget_usd": {
      "type": "number",
      "description": "Max budget in USD"
    },
    "trip_type": {
      "type": "string",
      "enum": [
        "hotel_only",
        "fixed_package",
        "cruise",
        "service",
        "custom_itinerary"
      ],
      "description": "hotel_only (the default), fixed_package, cruise, service (private experiences) or custom_itinerary"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "description": "Results per page, up to 50 (default 10)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Results to skip, for the next page"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get the details of a hotel, package, cruise or private experience from search_trips, with a hotel's Virtuoso perks. Virtuoso records carry no published rate or availability; the advisor quotes those in writing within 24 hours.

{
  "type": "object",
  "properties": {
    "trip_id": {
      "type": "string",
      "description": "trip_id from search_trips, or a hotel's virtuoso_property_id"
    }
  },
  "required": [
    "trip_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check whether a request goes straight to Geisel Power, the Virtuoso advisor, for a quote (hotel stays always do).

{
  "type": "object",
  "properties": {
    "trip_id": {
      "type": "string"
    },
    "num_nights": {
      "type": "number",
      "default": 1
    },
    "num_travelers": {
      "type": "number",
      "default": 1
    }
  },
  "required": [
    "trip_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get the steps to book a hotel, cruise or experience found with search_trips. Geisel Power, the Virtuoso advisor, quotes it in writing within 24 hours (rate, taxes, the hotel's cancellation policy and the perks) and books only after the traveler approves. This tool sends nothing itself (request_sent: false). Hotel bookings carry no fee and nothing is charged by Stay Perks: the traveler pays the hotel directly.

{
  "type": "object",
  "properties": {
    "trip_id": {
      "type": "string"
    },
    "traveler_info": {
      "type": "object",
      "properties": {
        "full_name": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "phone": {
          "type": "string"
        },
        "num_travelers": {
          "type": "integer",
          "minimum": 1
        },
        "special_requests": {
          "type": "string"
        },
        "agent_note": {
          "type": "string"
        }
      },
      "required": [
        "full_name",
        "email",
        "num_travelers"
      ],
      "additionalProperties": false
    },
    "num_nights": {
      "type": "number",
      "default": 1
    }
  },
  "required": [
    "trip_id",
    "traveler_info"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check the status of an existing booking

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string"
    }
  },
  "required": [
    "booking_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel a booking request. A confirmed hotel reservation is cancelled with the hotel under its own cancellation policy, which comes with the quote and the confirmation.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "description": "Reason for cancellation"
    }
  },
  "required": [
    "booking_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

WRITE. Ask Geisel Power, the Virtuoso advisor, to price a stay at a Virtuoso hotel (property_id from search_trips). Virtuoso data carries no live rates, so pricing is asynchronous: this returns a quote id with status "pending" and a quote_due_by time (within 24 hours); poll get_availability_quote. A firm offer includes the full total, taxes and fees, the hotel's cancellation policy, and the Virtuoso amenities (e.g. breakfast for two, a hotel credit, an upgrade, subject to availability). Nothing is reserved or charged by this call, and hotel bookings carry no fee.

{
  "type": "object",
  "properties": {
    "property_id": {
      "type": "string",
      "description": "Virtuoso property id (virtuoso_property_id) from search_trips"
    },
    "start_date": {
      "type": "string",
      "description": "Check-in date, YYYY-MM-DD"
    },
    "end_date": {
      "type": "string",
      "description": "Check-out date, YYYY-MM-DD"
    },
    "adults": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of adults"
    },
    "children": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of children"
    }
  },
  "required": [
    "property_id",
    "start_date",
    "end_date",
    "adults"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

READ. Returns the status of a quote from search_availability: "pending" (try again later), "quoted" (offers with stay_id, full total, cancellation terms), "unavailable", or "expired". Use an offer's stay_id with create_booking_session.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string",
      "description": "Quote id returned by search_availability"
    }
  },
  "required": [
    "quote_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

WRITE. Opens a UCP lodging booking session from a quoted offer (stay_id from get_availability_quote). Returns the authoritative total, the cancellation policy (show it to the traveler), the Virtuoso amenities, the payment term (pay at the hotel) and evidence. Nothing is charged; the session is held until the quote expires.

{
  "type": "object",
  "properties": {
    "property_id": {
      "type": "string"
    },
    "stay_id": {
      "type": "string",
      "description": "stay_id of a quoted offer"
    },
    "adults": {
      "type": "integer",
      "minimum": 1
    },
    "children": {
      "type": "integer",
      "minimum": 0
    },
    "booker": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone_number": {
          "type": "string"
        }
      },
      "required": [
        "first_name",
        "last_name",
        "email"
      ],
      "additionalProperties": false,
      "description": "Lead traveler (legal name + email). Without it the session stays \"incomplete\"."
    }
  },
  "required": [
    "property_id",
    "stay_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

READ. Current state of a booking session: ready_for_complete (awaiting the traveler's approval), complete_in_progress (the advisor is placing the reservation), completed (includes the hotel's own confirmation number; the traveler is also emailed), or canceled.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

WRITE. Change occupancy (within the quote) or set the booker before completing. Not allowed after completion.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string"
    },
    "adults": {
      "type": "integer",
      "minimum": 1
    },
    "children": {
      "type": "integer",
      "minimum": 0
    },
    "booker": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone_number": {
          "type": "string"
        }
      },
      "required": [
        "first_name",
        "last_name",
        "email"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

SENSITIVE WRITE — get the traveler's explicit approval of the full total and the hotel's cancellation policy first. Asks Geisel Power to place the reservation. No payment is taken: the traveler pays the hotel directly under its own terms, and hotel bookings carry no fee. Returns complete_in_progress with a confirmation deadline (within 24 hours); poll get_booking_session for the hotel's confirmation number, which is also emailed to the traveler.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string"
    },
    "booker": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone_number": {
          "type": "string"
        }
      },
      "required": [
        "first_name",
        "last_name",
        "email"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "session_id",
    "booker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

SENSITIVE WRITE. Withdraws a booking before the hotel confirms it (the advisor is told). Confirmed reservations are cancelled with the hotel under its cancellation policy, through the advisor.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}