API Reference

This section documents every operation exposed by the TTDbooking Stays API. Each endpoint has its own page covering the complete request and response contract; this page explains how those endpoints fit together and the order to call them in.

All operations use POST and are served over HTTPS. The pages that follow cover what every endpoint shares before you descend into the catalogue:

• Conventions — the response envelope, why the body code outranks the HTTP status, data formats, occupancy and session semantics, and idempotency.
• Common headers — Authorization, Session-Id, tracing, localisation, currency, market and timeout headers, plus the headers you get back.
• Generic types — the shared structures (Money, Rate, RoomRatePkg, cancellation fees, boards, taxes, order status) referenced by every endpoint page.

Base URLs

Build and certify against the test environment first, then switch the base URL to production when you go live. Nothing else in your integration needs to change.

Recommended integration flow

The diagram below shows the calls a typical integration makes, from authentication through to reading back an order.

sequenceDiagram
    participant C as Client
    participant A as API Gateway
    participant S as Search Service
    participant T as Trade Service
    participant P as Supplier Center
    Note over C, P: 1. Authentication
    C ->> A: POST /api/auth/ticket
    A ->> C: JWT Token
    Note over C, P: 2. Hotel Search
    C ->> A: POST /api/search/hotelList (with JWT)
    A ->> S: Hotel list request
    S ->> P: Call supplier search
    P ->> S: Return hotel list [with rates]
    S ->> A: Process and cache results
    A ->> C: Return hotel list [with rates]
    Note over C, P: 3. Rate Query [Optional]
    C ->> A: POST /api/search/hotelRates
    A ->> S: Rate query request
    S ->> P: Get real-time rates
    P ->> S: Return rate information
    S ->> A: Return rate details
    A ->> C: Return rate package information
    Note over C, P: 4. CheckAvail (price confirmation) [Optional]
    C ->> A: POST /api/search/checkAvail
    A ->> S: checkAvail request
    S ->> P: checkAvail request
    P ->> S: Return availability & price confirmation
    S ->> A: Return confirmation details
    A ->> C: Return confirmation details
    Note over C, P: 5. Booking (instant confirmation)
    C ->> A: POST /api/trade/book
    A ->> T: booking request
    T ->> P: Forward booking to supplier
    P ->> T: Return booking confirmation
    T ->> C: Booking confirmation
    Note over C, P: 6. Order Status Query
    C ->> A: POST /api/trade/queryOrders
    A ->> T: Query order
    T ->> A: Return order status with details
    A ->> C: Return order status with details

Sequence at a glance

Steps 3 and 4 are marked optional because the flow is technically valid without them. In practice both are strongly recommended: HotelRates is how you obtain the full set of bookable packages for a property, and CheckAvail re-confirms price and availability immediately before you commit the booking.

Authentication

Call POST /api/auth/ticket to exchange your credentials for a JWT. Send that token with every subsequent request — search, booking and order-management calls are all authenticated the same way.

See the Ticket reference for the credential fields, token lifetime and how to present the token on later calls.

OAuth 2.0 as an alternative

If your HTTP client already speaks OAuth 2.0, you can use the client_credentials grant (RFC 6749 §4.4) instead of the ticket exchange, on the same endpoints. Ask your account manager to register a client; you will receive a client_id and client_secret.

POST /api/v1/oauth/token
Content-Type: application/json

{ "grant_type": "client_credentials", "client_id": "...", "client_secret": "...", "scope": "search:read booking:write" }

The response carries an opaque access_token that you present exactly as you would a ticket: Authorization: Bearer <access_token>. Three differences are worth knowing before you choose:

• Scopes are mandatory. A ticket issued before scopes existed carries an empty list and has full access; an access token must carry the scope for each operation it calls — search:read, content:read, booking:read, booking:write, booking:cancel — and a token with no scopes is refused. You may request a subset of what your client is registered for; asking for anything else returns invalid_scope.
• Tokens are revocable. They are stored, not stateless, so a revocation takes effect immediately rather than when the token would have expired.
• Order-status callbacks need a ticket credential. callbackUrl on POST /api/trade/book registers a webhook signed with your Trade API key's secret, which an OAuth client does not have. Authenticate with a ticket to register callbacks, or poll QueryOrders instead.

Endpoint catalogue

Authentication

Content

Static content endpoints describe destinations and properties. They are not priced or date-bound, so their responses can be cached and refreshed on your own schedule rather than fetched per search.

Search

Make bookings

Manage bookings

Related guides

• Conventions — the envelope, formats and session/idempotency rules shared by every call.
• Booking flow — the four-call search-to-confirmation sequence explained step by step.
• Error handling — response codes and how to react to each class of failure.
• Rate limit — per-endpoint request limits and throttling behaviour.

Need help?

Questions about the API or your integration: integrations@ttdbooking.com Full documentation: developer.ttdbooking.com/hotel-api/docs