Despegar.com - Hotels, flights, packages, cars, and more!

## Booking Data Structures

The Booking Handling [Pull][Booking Handling (Pull)] and [Push][Booking Handling (Push)] APIs will include
the following data structures in their messages.

Please refer also to the examples for [Pull][Booking Handling (Pull) Examples] and [Push][Booking Handling (Push) Examples].

If you spot any errors on this page, please [let us know][contact] about it.

##### <a name="HotelReservationType"></a>HotelReservationType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| @CreateDateTime                               |   1    | It's the date and time of the moment in which the booking was made. It's mandatory if the attribute ResStatus is "Book".|
| @LastModifyDateTime                           |  0..1  | Indicates the date and time of the last booking modification. It's mandatory if ResStatus is "Modify" or "Cancel". |
| @ResStatus                                    |   1    | Booking status. Possible values: <ul><li> "Book": booked. </li><li> "Modify" : modified. </li><li> "Cancel".: canceled. </li></ul>|
| HotelReservation / POS / Source               |   1    | Reservation origin. |
| HotelReservation / POS / Source /BookingChannel / CompanyName                  |   1    | Name of the booking origin. |
| @ISOCountry                                   |   1    | Country where the reservation originated. |
| HotelReservation / ResGlobalInfo              |   1    | Contains general booking information. See [ResGlobalInfoType](#ResGlobalInfoType)|
| HotelReservation / RoomStays / RoomStay       |  0..n  | A RoomStay instance for every room of the booking. This element is always present if the ResStatus is “Book” or “Modify”, if the status is "Cancel" there is no RoomStay. See [RoomStayType](#RoomStayType)|
| HotelReservation / ResGuests / ResGuest       |  0..n  | One ResGuest per booking guest. ResGuests can't always be linked to the RoomStays. See [ResGuestType](#ResGuestType)|

##### <a name="ResGlobalInfoType"></a>ResGlobalInfoType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| HotelReservationIDs / HotelReservationID      |  0..2  | The object HotelReservationID contains several (ReservationId). |
| @ResID_Type                                   |   1    | Define the Booking ID type. Possible value <ul><li> 24: Travel Agent PNR </li></ul>|
| @ResID_Value                                  |   1    | Value that indicates the booking number. |
| SpecialRequests                               |  0..1  | |
| SpecialRequests / SpecialRequest              |  0..1  | The SpecialRequest object indicates special requests for a particular guest, service or reservation. |
| SpecialRequest / Text                         |  0..1  | |
| Total                                         |  0..1  | The total amount for the booking. They are added to the total amount of Roomstay. See [TotalType](#TotalType)|
| Fees / Fee                                    |  0..n  | |
| Fee / Amount                                  |  0..1  | Fee monetary amount |
| Fee / CurrencyCode                            |  0..1  | Fee Currency code. |
| Fee / ChargeUnit                              |  0..1  | This is the unit for which the charge applies (e.g. room, person, seat). Refer to OpenTravel Code List Charge Type (CHG). Values: <ul><li> 7 “Per person” </li><li> 25 “Per room” </li><li> 26 “Per reservation” </li></ul>|
| Fee / ChargeFrequency                         |  0..1  | This is the timeframe used to apply the charge during the course of the reservation (e.g. Daily, Weekly, Stay). Refer to OpenTravel Code List Charge Type (CHG). Values: <ul><li> 1 “Daily” </li><li> 12 “Per Stay" </li></ul>|
| Fee / Description / Text                      |  0..1  | Description identifies the fee type |
| DepositPayments                               |  0..1  | Contains the deposit information. This element rules out `Guarantee` and its presence indicates a _prepay_ reservation. |
| DepositPayments / GuaranteePayment            |   1    | |
| @GuaranteeType                                |   1    | An enumerated type defining the guarantee to be applied to this reservation. Values: <ul><li> PrePay </li></ul>|
| DepositPayments / GuaranteePayment / AcceptedPayments | 1 | |
| AcceptedPayments / AcceptedPayment            |   1    | |
| @GuaranteeTypeCode                            |   1    | Values: <ul><li> 43: Virtual card </li><li> 28: Wire transfer </li></ul> |
| AcceptedPayment / PaymentCard                 |  0..1  | This element will only appear for for `@GuaranteeTypeCode` 43 — Virtual card. |
| @ExpireDate                                   |   1    | This is the credit card's expiration date. MMaa format |
| PaymentCard / CardType                        |   1    | Credit card type. Possible values: <ul><li> CA — MasterCard </li></ul> **These values do not follow the OTA standard**. |
| PaymentCard / CardHolderName                  |   1    | Name of credit card's holder. |
| PaymentCard / CardNumber / PlainText          |   1    | The number embossed on the payment card, in plain format. |
| PaymentCard / SeriesCode / PlainText          |   1    | The card's security code. |
| AcceptedPayment / BankAcct                    |  0..1  | This element will only appear for for `@GuaranteeTypeCode` 28 — Wire transfer. |
| @Type                                         |   1    | The type of bank account involved in the wire transfer. Possible values: <ul><li> Checking </li></ul> |
| Guarantee                                     |  0..1  | Guarantee. See [GuaranteeType](#GuaranteeType). This element rules out `DepositPayments` and its presence indicates a _pay at destination_ reservation. |
| Comments / Comment / Text                     |  0..n  | Booking comment. |

##### <a name="ResGuestType"></a>ResGuestType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| @ResGuestRPH                                  |  0..1  | This value links ResGuest to Roomstay (s) whenever is possible. The links can be found in Roomstay / ResGuestRPHs. |
| Comment / Text                                |   1    | Guest additional information. |
| ResGuest / Comments / Comment                 |  0..1  | Place for guest additional information.|
| ResGuest / Profiles                           |   1    | Contains the guest profile information. See [ProfilesType](#ProfilesType) |

##### <a name="RoomStayType"></a>RoomStayType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| RoomStay / RatePlans / RatePlan               |   1    | The RatePlan for this Roomstay. This is not an actual RatePlan with an actual RatePlanCode but a container for common information that applies to the whole Roomstay.
| RatePlan / MealsIncluded / MealPlanType       |   1    | The MealPlanType applying to this Roomstay. Refer to OpenTravel [Meal Plan Type (MPT)](http://adriatic.pilotfish-net.com/ota-modelviewer/model/codelists/ota?term=MPT) code table.|
| RoomStay / RoomRates / RoomRate               |  1..n  | Multiple RoomRates per Roomstay. Multiple rates per each room rate. This can happen when there's a single room booked but more than one rate plan that applies for the stay. See [RoomRateType](#RoomRateType)|
| RoomStay / GuestCounts / GuestCount           |  0..4  | How many guests will be staying in the room? The count is divided in four potential elements GuestCount under GuestCounts one per each client type: adults, children, infants or babies.|
| @AgeQualifyingCode                            |   1    | Define the age range of the guest. Possible values: <ul><li> 10: Adult (Only for per room per night) </li><li> 8:Child </li><li> 7:Infant </li><li> 3: Baby </li></ul> |
| @Count                                        |   1    | The type of guest number |
| RoomStay / TimeSpan                           |   1    | Contains the room stay.|
| @Start                                        |   1    | Check in date |
| @End                                          |   1    | Check-out date|
| RoomStay / Total                              |  0..1  | Booking total amount. The cost of all the rooms is added. See [TotalType](#TotalType) |
| RoomStay / BasicPropertyInfo                  |   1    | Property information. |
| @HotelCode                                    |   1    | The hotel code |
| RoomStay / ServiceRPHs / ServiceRPH           |  0..n  | Contains links to any service or extra charges for the room |
| @RPH                                          |   1    | Links the Service/@ServiceRPHA for this RoomStay |
| RoomStay / ResGuestRPHs / ResGuestRPH         |  0..n  | Used to link ResGuests to the Roomstay |
| @RPH                                          |   1    | Links the ResGuest/@ResGuestRPH to this RoomStay |
| RoomStay / Comments / Comment / Text          |  0..1  | Roomstay comments |
| RoomStay / SpecialRequests                    |  0..n  | At a room level, the special requests represents the list of value added offers included for this type of room in this reservation. |
| RoomStay / SpecialRequests / SpecialRequest   |  0..1  | At a room level, this represents a single value added offer for this room and this reservation. |
| RoomStay / SpecialRequests / SpecialRequest / Text |  0..1  | A description of the value added offer included |

##### <a name="RoomRateType"></a>RoomRateType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| RoomStay / RoomRates / RoomRate               |  1..n  | Multiple RoomRates per Roomstay. There may be multiple room rates for each RoomRate This can happen when there's a room booked but more than one rate plan that applies during the stay.|
| @RoomTypeCode                                 |   1    | Booked room Code |
| @NumberOfUnits                                |   1    | Always 1. Each room will be included in its own Roomstay element.|
| @RatePlanCode                                 |   1    | Rate plan code reserved for the type of room code that appears in the attribute RoomTypeCode.|
| @InvBlockCode                                 |   1    | This code identifies the type of inventory block and indicates whether the availability used for this RoomRate in the Reservation is PUBLIC (shared with other OTAs) or PRIVATE. Please read further [here](/portal/documentation/booking-handling-pull#AvailabilityAdjust). | 
| RoomRate / Rates                              |  0..1  | Itemized rates daily information. |
| Rates / Rate                                  |  1..n  | The rate element has a time interval with daily rate information. The dates in the rates will cover all the dates in the element / TimeSpan Roomstay.|
| @EffectiveDate                                |   1    | The start date of the rate in the format yyyy-MM-dd. This date is inclusive. |
| @ExpireDate                                   |   1    | Rate end date. Format yyyy-MM-dd. This date is exclusive. |
| Rate / Discount                               |  0..1  | Discount percentage and/or Amount, code and textual reason for discount |
| @Percent | 1 | |
| Discount / DiscountReason | 1 | |
| @name                                         |   1    | Name of discount |
| Rate / Total                                  |  0..1  | The total amount charged for the rate. It will the same as the base with the extras and discounts applied. See [TotalType](#TotalType)|
| Rate / AdditionalGuestAmounts                 |  0..1  | See [TotalType](#TotalType) |
| AdditionalGuestAmounts / AdditionalGuestAmount|  0..n  | |
| @Amount                                       |  0..1  | Extra charge amount. |
| @AgeQualifyingCode                            |   1    | Define the age range of the extra guest. Possible values: <ul><li> 10: Adult (Only for per room per night) </li><li> 8:Child </li><li> 7:Infant </li><li> 3: Baby </li></ul> |

##### <a name="GuaranteeType"></a>GuaranteeType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| @GuaranteeType                                |   1    | An enumerated type defining the guarantee to be applied to this reservation. Values:  <ul><li> CC/DC/Voucher — for pay at destination reservations. </li><li> None — for cash reservations.</li></ul>|
| Guarantee / GuaranteesAccepted / GuaranteeAccepted / PaymentCard | 0..1 | Contains information about the payment card, if applicable. |
| @ExpireDate                                   |   1   | This is the credit card's expiration date. MMAA format |
| PaymentCard / CardType                        |   1   | Credit card type. Possible values: <ul><li>AX — American Express</li><li>CL — Cabal</li><li>CB — Carte Blanche</li><li>CS — Cencosud</li><li>DC — Diners</li><li>DS — Discover</li><li>EC — Elo</li><li>HC — HiperCard</li><li>PR — Presto</li><li>MG — Magna</li><li>CA — MasterCard</li><li>MD — MasterCard Débito</li><li>NT — Nativa</li><li>TN — Tarjeta Naranja</li><li>VI — Visa</li><li>VD — Visa Débito</li></ul> **These values do not follow the OTA standard**.|
| PaymentCard / CardNumber                      |   1   | The number embossed on the payment card. |
| PlainText                                     |  0..1 | The plain text credit card number — only included in reservations delivered via push.|
| @Mask                                         |  0..1 | The masked credit card number — included in reservations queried via the pull API.|
| PaymentCard / CardHolderName                  |   1   | Name of credit card's holder. |

##### <a name="ProfilesType"></a>ProfilesType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| Profiles / ProfileInfo                        |  1..n  | Profile Information |
| ProfileInfo / Profile                         |   1    | Contains profile information |
| @ProfileType                                  |   1    | Profile type See OTA code tables (Profile type - PRT). Possible values:  <ul><li> 1:Customer </li><li> 2:GDS </li><li> 3:Corporation </li><li> 4:TravelAgent </li></ul>|
| Profile / Customer | | |
| Customer / PersonName / GivenName             |   1    | Customer's first name |
| Customer / PersonName / MiddleName            |  0..1  | Customer's middle name |
| Customer / PersonName / Surname               |   1    | Customer's surname |

##### <a name="TotalType"></a>TotalType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| @CurrencyCode                                 |  0..1  | The currency code for the total amounts (ISO currency code) |
| @AmountAfterTax                               |  0..1  | Total amount after taxes. |
| @AmountBeforeTax                              |  0..1  | Total amount before taxes. |
| @AmountIncludingMarkup                        |   1    | This amount includes markup and taxes. Possible values: <ul><li> True </li><li> False </li></ul>|
| @AdditionalFeesExcludedIndicator              |   1    | This amount exclude feed. Possible values: <ul><li> True </li><li> False </li></ul>|
| Taxes                                         |  0..1  | The total amount of taxes for TotalType. See [TaxesType](#TaxesType) |
| @Amount                                       |  0..1  | Total amount of taxes. |

##### <a name="TaxesType"></a>TaxesType

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| Taxes / Tax | 0..n | |
| @Code                                         |   1    | The code of the tax type applied to the total. Reference to the OTA tax code table: OTA Fee Tax Type (FTT)|
| @Percentage                                   |  0..1  | Tax percentage |
| @Amount                                       |  0..1  | Tax amount |
| Tax / TaxDescription / Text                   |  0..1  | Descriptive tax text type |

[contact]: <mailto:channels@despegar.com>
  [Booking Handling (Pull)]: </portal/documentation/booking-handling-pull>
  [Booking Handling (Push)]: </portal/documentation/booking-handling-push>
  [Booking Handling (Pull) Examples]: </portal/documentation/examples/booking-handling-pull>
  [Booking Handling (Push) Examples]: </portal/documentation/examples/booking-handling-push>