HOTELS

Yes. When more detailed information is available, the API returns a subcategory code, such as "BRA" or "BRB", instead of the general parent code, such as B.
Partners should map both general codes and their subcategories. The full list is available through the /meal-plans service in API Common Assets.

No new categories are expected. All possible fee concepts for charge_at_destination are available through the /fee-types service in API Common Assets.

No. All properties are returned in a single response. offset and limit parameters are not available.
Filters are planned for a future iteration, but pagination is not currently planned.

No dedicated catalog service is currently available for room-level amenities. If needed, contact the support team to request the corresponding JSON file.

No. The response includes only city_id, latitude, and longitude.
Complete location information, such as city name, administrative division, country, and time zone, is available through the Geography service in API Common Assets.

Currently, the service returns the full global catalog. A solution to return only partner-eligible properties is in progress.

No. These parameters are not supported for inline filtering. The service always returns the same response structure.

Availability can be searched up to 540 days in advance.

The maximum occupancy per room is 8 guests, including adults and children.

Up to 4 rooms can be requested per search.

The maximum length of stay is 30 days.

This field indicates the refundability status at the time of the request.
Possible values are:

• fully_refundable: Free cancellation is currently available. See cancellation_policy_rules for the applicable conditions.
• partially_refundable: A partial penalty applies from the time of booking. See cancellation_policy_rules for the applicable conditions.
• non_refundable: A 100% penalty applies immediately. The cancellation_policy_rules field is empty.

Possible values are:

• cancellation
• no_show

These values must not be combined within the same rule entry.

The range is expressed in hours before check-in and must be read from the smallest value to the largest.
The reference point is 00:00:00 on the check-in date. For example, "from": 0 and "to": 96 applies from check-in time up to 96 hours (4 days) before check-in.

The charge_at_destination field includes amounts payable directly at the property, such as local or legally required fees. These amounts are not included in price_detail.total.
Fee types can be mapped using the /content-api/hotels/fee-types endpoint. This field is returned only when the hotel has destination charges registered.

The taxes field returns a single entry with the base code. This amount is included in price_detail.total.

No. This field may be absent when the room is not available in Despegar's static content. Filtering out roompacks without room_type_id is valid and recommended.

Yes. Some variation from the previous /Availability response may occur due to provider caching. This is expected behavior.

All rates returned by the API are prepaid. Pay-at-destination options are not available.

No. The number of remaining rooms is not returned by the /Availability endpoint.

Roompacks are sorted by default in ascending price order, from lowest to highest. There is no configurable sorting option, and best_selling_descending is not supported.

No. Context parameters such as context, alternative_contexts, and alternative_rates are not supported. The API operates under a distribution-channel model, where different rate types are provided through separate API credentials. Contact your Account Manager to ensure the required distribution configuration is enabled.

The /prebook service should be used as the equivalent of the check rate step, typically on the checkout page. It validates the selected option’s availability and price and generates a /prebook_id token valid for 15 minutes.
If the token expires before completing the booking, the /prebook service must be called again.

Currently, price changes between the /availability/{hotel_id} (Detail) and /prebook services are not supported. If this becomes available in the future, it will be indicated in the /prebook response.

The currency returned by the Search and /availability/{hotel_id} (Detail) services is informational. The /prebook service always returns amounts in the current account currency configured for the API credentials. This behavior is expected.

No. The /prebook service validates price and availability with the supplier but does not create a hold or reservation.
The /prebook_id expires after 15 minutes and has no side effects. If the Book service is not called, no cancellation is required.

For partners using the CURRENT_ACCOUNT payment model exclusively, the /payments service can be skipped.
For partners using the COMMISSIONABLE model, the /payments service is mandatory.

Only first_name and last_name are required for each traveler. gender, nationality, birth_date, and identification /availability/{hotel_id} (Detail)s are not mandatory for hotel bookings.
One lead traveler must be provided for each room.

• reservation_id: Internal reservation identifier. Used to retrieve reservation /availability/{hotel_id} (Detail)s.

  • platform_id: Product-level identifier required for after-sales operations.
  • reservation_number (PNR): Hotel reference number used for check-in and customer support.

  Both reservation_id and platform_id can be used as query parameters in the /reservations service.

No. Partial cancellations are not supported. All rooms included in the reservation must be cancelled together.

There is no mandatory minimum wait time. However, it is recommended to wait at least 60 seconds after booking confirmation before attempting a cancellation, to allow internal synchronization to complete.

The possible status values are:

• IN_PROCESS
• ISSUED
• CANCELLED
  These values are consistent across all products.

Yes. When filtering by purchase date, the by_api_key=true parameter must also be included.
Example:
GET //reservations?by_api_key=true&from_purchase_date=2026-01-01&to_purchase_date=2026-06-29

Yes. The cancellation flow requires the /allowance, /quote, and /cancel services to be called in that order. The flow cannot be bypassed.

Most hotel IDs remain the same. However, some IDs may differ due to internal hotel ID merges.
When applicable, merged IDs are returned by both the /availability (Search) and content-api/ (Hotels Content) services.

No. Meal plan codes differ between versions.
Use the /meal-plans service in API Common Assets to map the new codes.

Yes. Both versions can coexist during a gradual traffic migration.
Once API v3 has been validated, it is recommended to keep only one API version active.

Yes, reservations created through the previous API can generally be cancelled through API v3.
Some exceptions may apply. Contact the support team to validate whether a specific reservation is eligible for cancellation through API v3.