Despegar Availability API
The Availability API from Despegar — 2 operation(s) for availability.
OpenAPI Specification
openapi: 3.0.3
info:
title: Activities Availability API
version: 1.0.0
description: 'API for activities: tickets, modalities, availability, prebook, payments, and booking. Authentication via API Key.'
servers:
- url: https://api-dev.despegar.com/v3/activities-api
description: Sandbox
- url: https://apis-uat.despegar.com/v3/activities-api
description: UAT
- url: https://api.despegar.com/v3/activities-api
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Availability
paths:
/availability:
get:
tags:
- Availability
summary: Availability
parameters:
- in: query
name: id
schema:
type: string
required: true
description: This information must be obtained from the response of the 'Modalities' service,
- in: query
name: modality
schema:
type: string
required: true
description: 'Modality chosen by the user; this information must be obtained from the detail service response, in the structure: ''modalities'' -> ''id''.'
- in: query
name: date
schema:
type: string
format: date
required: true
description: Date on which the activity will take place; the format to send is YYYY-MM-DD.
example: '2026-04-04'
- in: query
name: site
schema:
type: string
example: br
required: true
description: Refers to the country code; it must contain two alphabetic characters
- in: query
name: language
schema:
type: string
enum:
- es
- pt
- en
required: true
description: This field must be filled with the language in which you want to receive the response
- in: query
name: additionals
schema:
type: string
required: false
description: Refers to the ID of the additional attraction; this information must be obtained from the response of the 'Modalities' service, field 'id' within the 'additionals' structure.
- in: query
name: distribution
schema:
type: string
example: 2-8-8-4-4
default: '1'
required: false
description: ' In this field, send the distribution of people in the activity. The first position always refers to the number of adults; the remaining positions should be the ages of the minors (children or infants).Example: for an activity with 2 adults, two 8-year-olds, and two 4-year-olds '
- in: query
name: schedule
schema:
type: number
example: 09:30
required: false
description: ' In this field, send the distribution of people in the activity. The first position always refers to the number of adults; the remaining positions should be the ages of the minors (children or infants).Example: for an activity with 2 adults, two 8-year-olds, and two 4-year-olds '
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
choice_id:
type: string
description: ID generated to identify the ticket data and the valid fare to make the reservation.
name:
type: string
description: Attraction name.
modality_choice_name:
type: string
description: Name of the chosen modality.
type:
type: string
description: Refers to the type of activity.
language:
type: string
description: Identifies the language.
site:
type: array
description: ' identifies the country code.'
destination:
type: array
description: IATA code identifying the destination.
from:
type: string
format: date
description: Date on which the search was performed.
to:
type: string
format: date
description: Date on which the search was performed.
distribution:
type: object
properties:
adults:
type: integer
adults_ages:
type: array
children_ages:
type: array
infants_ages:
type: array
adult_max_age:
type: number
child_max_age:
type: number
infant_max_age:
type: number
additions_chosen:
type: array
items:
type: object
properties:
title:
type: string
description:
type: string
prices:
type: object
description: This array contains the reservation prices by currency. USD is always included by default, and an additional local currency may be returned depending on the site.
price_details:
type: array
items:
type: object
properties:
total:
type: number
currency:
type: string
currency_to_usd_change_rate:
type: number
usd_to_currency_change_rate:
type: number
net:
type: number
tax:
type: number
gross:
type: number
price_disaggregation:
type: object
properties:
agency_commission:
type: object
properties:
gross:
type: number
net:
type: number
tax:
type: number
cancellation_policy:
type: object
properties:
title:
type: string
cancellable:
type: boolean
ranges:
type: array
items:
type: object
properties:
from:
type: string
format: date
to:
type: string
format: date
penalty:
type: object
properties:
USD:
type: number
BRL:
type: number
percentage:
type: string
label:
type: string
conditions:
type: array
'400':
description: Invalid request
content:
application/json:
schema:
oneOf:
- title: ACTIVITY_PROVIDER_ERROR
type: object
properties:
Message:
type: string
description: Bad request on activity provider due to invalid field value.
Possible_cause:
type: string
description: '''distribution'' parameter sent with invalid value'
- title: INVALID_FIELD
type: object
properties:
Message:
type: string
description: Request validation error — missing, blank, invalid, or out-of-policy values in Availability parameters (ticket_id, modality, date, site, language).
Possible_cause:
type: string
description: 'The Availability call was sent with incorrect inputs: ticket_id not provided/blank or not in the allowed set, modality missing/blank, date earlier than today, site blank/invalid, or language blank/invalid.'
- title: MISSING_REQUIRED_PARAMETER
type: object
properties:
Message:
type: string
description: Missing required parameters in Availability request
Possible_cause:
type: string
description: 'The request was sent without one or more required fields: ticket_id, modality, date, site, or language.'
'503':
description: Invalid request
content:
application/json:
schema:
oneOf:
- title: ACTIVITY_PROVIDER_ERROR
type: object
properties:
Message:
type: string
description: Error with activity provider
/hotels-api/availability/{hotel_id}:
get:
summary: Detail
description: Returns live availability for a specific hotel.
parameters:
- in: path
name: hotel_id
schema:
type: string
required: true
description: ' Refers to the id of the hotel.'
- in: query
name: country_code
schema:
type: string
description: ' Refers to the country code, which must be filled with two alphabetical digits.'
example: br
- in: query
name: checkin_date
schema:
type: string
format: date
required: true
description: Refers to the hotel check-in date and must be in the format YYYY-MM-DD.
example: '2026-11-14'
- in: query
name: checkout_date
schema:
type: string
format: date
required: true
description: Refers to the hotel check-out date and must be in the format YYYY-MM-DD.
example: '2026-11-16'
- in: query
name: currency
schema:
type: string
required: true
description: Refers to the currency, which must be filled with three alphabetical digits. (E.g. "USD", "ARS")
example: BRL
- in: query
name: distribution
schema:
type: string
required: true
description: 'Passenger distribution. Each room’s passengers should be written as number_of_adults-children_ages. Children-age goes up to 17 years old. Rooms should be separated by “!”. E.g.: Means room 1 with 2 adults and room 2 with 2 adults and a 10-year-old child.'
example: 2!2-10
- in: query
name: roompack_id
schema:
type: string
description: specific roompack_id (obtained in previous step).
- in: query
name: language
schema:
type: string
enum:
- EN
- ES
- PT
description: Refers to the language, which must be filled with two alphabetical digits.
example: PT
- in: query
name: ttl
schema:
type: integer
description: Maximum time allowed for the connection. Minimum = 3000 ms, Maximum = 6200 ms.
- in: query
name: refundable_only
schema:
type: boolean
description: If set to ‘true’, only refundable hotel rates will be quoted.
responses:
'200':
description: Detailed availability for the hotel
content:
application/json:
schema:
type: object
properties:
id:
type: integer
hotel_info:
type: object
description: This structure is of type dictionary and returns hotel information.
properties:
type:
type: string
roompacks:
type: array
items:
type: object
properties:
id:
type: string
description: roompack id
meal_plan:
type: object
description: Meal plan corresponding to the roompack (e.g., room only, breakfast included, all-inclusive, etc.).
properties:
id:
type: string
price_detail:
type: object
properties:
currency:
type: string
description: currency in which values will be expressed
total:
type: number
description: total value of the roompack (subtotal + taxes). It does not include charges to be paid at destination
taxes:
type: number
description: taxes corresponding to the roompack price
taxes_detail:
type: array
description: list with code and amount pairs
items:
type: object
properties:
code:
type: string
amount:
type: string
binding_public_rate_enabled:
type: boolean
description: if set to true, “amount” value is the mínimum price that the partner should sell the item
binding_public_rate_value:
type: integer
agency_commission:
type: object
description: Applicable only to commissionable models.
properties:
amount:
type: number
percentage:
type: number
charge_at_destination:
type: number
charge_at_destination_detail:
type: array
items:
type: object
properties:
code:
type: string
amount:
type: number
cancellation_policy:
type: object
description: This structure is of type list and can return one or several rules regarding cancellation policies of the roompack
properties:
status:
type: string
description: Represents the cancellation policy status at the moment the request is made
enum:
- non_refundable
- partially_refundable
- fully_refundable
hours_before_penalty:
type: integer
description: hours prior to check in which status applies in case of cancelling in those conditions
vendor_notes:
type: string
description: string field with information regarding cancellation policies.
cancellation_policy_rules:
type: array
description: This structure is of type list and can return one or several rules regarding cancellation policies of the roompack. The penalty may be applied per night or as a percentage. Based on the information provided by the partner, the refund amount is determined. If no penalty is specified for that range, it is considered that no penalty applies.
items:
type: object
properties:
type:
type: string
description: rule type
penalty:
type: object
description: contains the percentage of the total amount of the reservation that should be considered as charge in case of cancelling in theses conditions
properties:
percentage:
type: number
night_count:
type: number
anticipation:
type: object
description: timeframe where the rules apply. it is a dictionary with “from” and “to” values measured in hours to check in.
properties:
from:
type: integer
to:
type: integer
rooms:
type: array
items:
type: object
properties:
name:
type: string
description: room name
reference:
type: integer
description: index of room elements contained in the roompack choice (first index == 1)
room_type_id:
type: string
description: room id.These id should be used to map static content about the room
bed_options:
type: array
description: list with all bedding options for the room
items:
type: object
properties:
id:
type: integer
description:
type: string
max_capacity:
type: integer
description: maximum pax capacity of the room
choice_id:
type: string
description: id to be used for prebook stage
promo:
type: object
properties:
type:
type: string
saving:
type: object
description: Details of the promotional savings associated with the product.
properties:
type:
type: string
percentage:
type: number
tags:
type: array
description: Used to identify products associated with a promotion.
categorized_notices:
type: object
description: Main container for categorized hotel notices, organized by importance level
properties:
primary:
type: object
description: PRIMARY notices category - Critical and priority information that guests must know obligatorily
properties:
title:
type: object
properties:
en:
type: string
description: This field is dynamically returned according to the language specified in the request
notices:
type: array
description: Array of individual notices within the primary category
items:
type: object
properties:
title:
type: object
properties:
en:
type: string
description: This field is dynamically returned according to the language specified in the request
messages:
type: array
description: This field is dynamically returned according to the language specified in the request
items:
type: object
properties:
en:
type: string
secondary:
type: object
description: SECONDARY notices category - Important but lower priority information, policies and operational details
properties:
title:
type: object
properties:
en:
type: string
notices:
type: array
description: Array of individual notices within the primary category
items:
type: object
properties:
title:
type: object
properties:
en:
type: string
messages:
type: array
description: This field is dynamically returned according to the language specified in the request
items:
type: object
properties:
en:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
tags:
- Availability
operationId: getHotelAvailability
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-apikey
BearerAuth:
type: http
scheme: bearer
x-readme: {}