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:

Rate — net, gross, commissionable

Prices carry three layers. Which layer you sell on depends on your commercial agreement:

{
  "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 and Book.

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:

"cancelFees": [
  { "until": "2026-01-01T18:00:00Z", "fee": { "amount": 0,  "currency": "USD" } },
  { "until": "2026-01-03T23:59:59Z", "fee": { "amount": 99, "currency": "USD" } }
]

BoardId — standard meal plans

Board codes follow the standard meal-plan enum:

A board object carries boardId (required) plus optional multilingual boardName and boardDesc.

RefundableMode

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.

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:

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 (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.

DestinationType

Classification of a destination record:

Empty search diagnosis

{ "list": [], "total": 0 } from HotelList 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.

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 and QueryOrders take a nested page object.
• HotelList takes pageNum / pageSize / cursor as flat top-level fields.

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