# Generic types The following structures recur across transactions. Every endpoint page links back here rather than restating them, the way the reference documentation this API is contract-compatible with publishes its "generic types" chapter once and references it everywhere. --- ## Money A monetary amount. Always a paired object — never a bare number: | Field | Type | Description | | ---------- | ------ | ------------------------------------- | | `amount` | number | Monetary amount, e.g. `14.50`. | | `currency` | string | Currency code, e.g. `USD` (ISO 4217). | --- ## Rate — net, gross, commissionable Prices carry three layers. Which layer you sell on depends on your commercial agreement: | Field | Type | Description | | -------------------- | ------- | -------------------------------------------------------------------------------- | | `netRate` | Money | **Required.** The supplier's base cost; non-commissionable. | | `grossRate` | Money | Usually the suggested retail price (SRP) or the hotel's best available rate. | | `commissionableRate` | Money | The basis used when calculating commission. | | `respectGrossRate` | boolean | When `true`, you must honour and display `grossRate` unchanged. Default `false`. | ```json { "netRate": { "amount": 100.0, "currency": "USD" }, "grossRate": { "amount": 129.0, "currency": "USD" }, "respectGrossRate": false } ``` **Day-by-day pricing is not available.** Suppliers generally treat nightly pricing as an average of the total rate, not true per-date amounts. If your product needs daily figures, contact the supplier. **Supported rate types, summarised:** - `netRate` — supplier's base cost; non-commissionable. - `commissionableRate` — the base for commission calculations (net rates also included). - `grossRate` — usually the SRP or the hotel's BAR. - `respectGrossRate` — flag: you must display/pass through the gross rate unchanged. > Tip: align selling prices with SRP guidance to avoid breaching supplier contracts. --- ## RoomRatePkg — the bookable offer The core structure of search and booking: one room offer for a given hotel, stay and occupancy. The `ratePkgId` is the key input for [CheckAvail](/hotel-api/docs/api-reference/check-avail) and [Book](/hotel-api/docs/api-reference/book). | Field | Required | Type | Description | | -------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `ratePkgId` | **Yes** | string | Unique identifier of this rate package. Opaque, and only resolvable inside the session that produced it — send that session's id in `Session-Id`. | | `refundableMode` | **Yes** | enum | Refundability — see [RefundableMode](#refundablemode) below. | | `refundableUntil` | No | string (RFC 3339) | Instant up to which the stated `refundableMode` applies. | | `cancelFees` | No | CancelFee[] | Computed cancellation policy steps — see [Cancellation fees](#cancellation-fees). | | `rate` | **Yes** | Rate | Single room price for multiple nights. | | `totalRate` | **Yes** | Rate | Total price for multiple rooms (and multiple nights). | | `checkIn` | **Yes** | string (`yyyy-MM-dd`) | Check-in date. | | `checkOut` | **Yes** | string (`yyyy-MM-dd`) | Check-out date. | | `board` | No | Board | Meal plan — see [BoardId — standard meal plans](#boardid-standard-meal-plans). | | `tax` | No | Tax | Taxes and fees, itemised separately — see [Tax](#tax) below. | | `originalRoomNaming` | No | object | Room naming exactly as received from the supplier: `id` (supplier's room code), `name`, `supplier` (supplier id). | | `rateComment` | No | string | Free-text comment attached to the rate by the supplier. | | `includesPackaging` | No | boolean | Whether this is a packaged product (e.g. flight + hotel combo). | ### Standardised room types Rooms are mapped by the Connectivity Bridge: `roomTypeId` (e.g. `"R001"`) and `roomTypeName` are standardised across suppliers. When a supplier's room type cannot be recognised, a fallback such as **"Standard Room"** is returned, and the supplier's own naming is preserved in `originalRoomNaming`. --- ## Cancellation fees `cancelFees` is an array of policy steps. Each step gives a deadline and the cancellation charge that applies until that deadline; a fee of `0` means cancellation is free until then: ```json "cancelFees": [ { "until": "2026-01-01T18:00:00Z", "fee": { "amount": 0, "currency": "USD" } }, { "until": "2026-01-03T23:59:59Z", "fee": { "amount": 99, "currency": "USD" } } ] ``` | Field | Type | Description | | ------- | ----------------- | ------------------------------------------------------------- | | `until` | string (RFC 3339) | Deadline for cancelling under this policy step. | | `fee` | Money | Cancellation charge applicable until `until`; `0` means free. | --- ## BoardId — standard meal plans Board codes follow the standard meal-plan enum: | Code | Meal plan | Code | Meal plan | | ---- | ------------------------------- | ---- | -------------------- | | `RO` | Room only | `BI` | Breakfast included | | `BB` | Bed and breakfast | `LU` | Lunch only | | `HB` | Half board (breakfast + dinner) | `DI` | Dinner only | | `FB` | Full board (three meals) | `BD` | Breakfast and dinner | | `AI` | All inclusive | `BL` | Breakfast and lunch | | `TI` | All inclusive (alternate code) | `LD` | Lunch and dinner | A `board` object carries `boardId` (required) plus optional multilingual `boardName` and `boardDesc`. --- ## RefundableMode | Value | Meaning | | --------- | -------------------- | | `full` | Free cancellation | | `partial` | Partial cancellation | | `no` | Not refundable | --- ## Tax Taxes and fees are typically collected by the hotel on the government's behalf; because they are fixed costs and are not marked up as the rate moves through distribution, they are itemised separately from the rate. | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------------- | | `total` | Money | Total taxes and fees. | | `items[].taxType` | string | Tax category, e.g. `VAT`, `SERVICE_CHARGE`, `CITY_TAX`. | | `items[].taxName` | string | Tax name. | | `items[].amount` | Money | Amount. | | `items[].desc` | string | Description. | Taxes are included in what you see on the rate: `rates[i].tax.total` and the itemised `rates[i].tax.items[]`. --- ## OrderStatus Status of an order — integer-encoded: | Value | Name | Meaning | Final? | | ----- | -------------------------- | ------------------------------------------------------------------------------------------------------ | ------ | | 0 | `OrderStatus_Unknown` | Unknown / indeterminate — must verify via [QueryOrders](/hotel-api/docs/api-reference/query-orders) | No | | 1 | `OrderStatus_Confirming` | Processing, not final | No | | 2 | `OrderStatus_Confirmed` | Confirmed — success | Yes | | 3 | `OrderStatus_Cancelled` | Cancelled | Yes | | 4 | `OrderStatus_Failed` | Failed | Yes | | 5 | `OrderStatus_CancelFailed` | Cancellation failed | Yes | **Non-final statuses after Book.** If the status returned is `1` (Confirming) or `0` (Unknown), do **not** reject immediately: persist `customerReferenceNo` and `supplierReferenceNo`, verify via [QueryOrders](/hotel-api/docs/api-reference/query-orders) (poll up to ~10 minutes: immediately, then 30 s, 1 m, 2 m, then back off), and never submit a second booking for the same intent while verification runs. If no final status has arrived after the window, leave the order pending and contact **integrations@ttdbooking.com** with the stored references. See [Error handling — non-final booking status](/hotel-api/docs/guides/error-handling). --- ## DestinationType Classification of a destination record: | Value | Name | Meaning | | ----- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | | 1 | Continent | A large landmass such as Europe, Asia or South America. | | 2 | Country | A nation-state. Drawn geographically rather than politically. | | 3 | ProvinceState | An administrative division inside a country, such as California; also lower-level divisions such as counties. | | 4 | HighLevelRegion | A tourist region, such as the Upper Rhine or wine country in California. | | 5 | MultiCityVicinity | A large metropolitan area covering a major city and its suburbs, such as Cairo. Boundaries drawn broadly by tourist value. | | 6 | City | An urban area. The base unit of geographic coverage; boundaries follow official administrative sources. | | 7 | Neighborhood | A geographic area smaller than a city, such as the old town in Bonn. | | 8 | Airport | An airport, such as LHR (London Heathrow). | | 9 | PointOfInterest | A museum, convention centre, beach, park or broader venue. | | 10 | TrainStation | A train station, such as Grand Central Terminal, New York. | | 11 | MetroStation | A subway station. | | 12 | BusStation | A bus station, such as the Port Authority Bus Terminal. | --- ## Empty search diagnosis `{ "list": [], "total": 0 }` from [HotelList](/hotel-api/docs/api-reference/hotel-list) has two causes that need opposite responses, and on its own it cannot tell you which you have hit: 1. **The suppliers were asked and had nothing.** Genuine zero availability — try other dates or another property. `basic.emptyReason` is absent. 2. **No supplier answered, or none was asked at all.** A configuration state on our side; retrying or changing dates/destination cannot change it. `basic.emptyReason.code` is present and says which. | `emptyReason.code` | Meaning | Retry? | | ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `NO_SUPPLIER_ENABLED` | No supplier is currently enabled for hotel search. | No — contact your account manager | | `NO_SUPPLIER_PERMITTED` | Suppliers are enabled, but none may serve your account on this search. | No — commercial/configuration matter | | `ALL_SUPPLIERS_EXCLUDED` | Every candidate was excluded before the search ran, by a market, currency, language or inventory restriction. | No — check request parameters | | `NO_SUPPLIER_ANSWERED` | Suppliers were called and every one of them failed. | **Yes** — the only one of the four worth retrying | Supporting fields on the search response: - `basic.statusRemark` — the same diagnosis as one human-readable sentence, suitable for a log line or an operator-facing message. - `basic.emptyReason.suppliers` — _which_ supplier failed and why. Disclosed only to accounts entitled to the supplier breakdown; most integrations will never see it, and its absence is not an error — `code` and `statusRemark` are complete without it. - `basic.notices` — belongs to a search that **worked**: what the response does not contain when the result is real but not complete (a destination expansion that hit its cap, properties dropped because they could not be priced in the requested currency). Never emitted alongside `emptyReason`. All of these fields are additive and optional: a client that ignores them behaves exactly as it did before they existed. --- ## Pagination Pagination parameters and where they live differ by endpoint: - [HotelsMetadata](/hotel-api/docs/api-reference/hotels-metadata) and [QueryOrders](/hotel-api/docs/api-reference/query-orders) take a nested `page` object. - [HotelList](/hotel-api/docs/api-reference/hotel-list) takes `pageNum` / `pageSize` / `cursor` as flat top-level fields. | Field | Type | Description | | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pageNum` | integer | Page number to retrieve. The first page is 1. | | `pageSize` | integer | Items per page. **Defaults differ:** 20 on HotelsMetadata, 100 on QueryOrders, 50 on HotelList — send it explicitly if the size matters to you. Maximum is 100 (HotelsMetadata, QueryOrders) or 200 (HotelList); a larger value is **rejected with code `100000400`**, not clamped. | | `cursor` | integer | Cursor pointing at the next page. | Responses carry `total` (a value of `0` means no items, or that totals are not supported for this query) and `hasMore`. --- ## Need help? Questions about the shared types or your integration: **integrations@ttdbooking.com** Full documentation: **[developer.ttdbooking.com/hotel-api/docs](https://developer.ttdbooking.com/hotel-api/docs)**