Booking.com Connectivity Integration Guide

A Booking.com Connectivity integration is not a collection of XML or JSON calls. Property setup, room-rate products, prices, inventory, restrictions and reservation messages jointly describe sellable state across two systems. Production architecture must synchronize that state in an ordered, replay-safe and reconcilable way.

For platform boundaries and operational ownership, see the Booking.com Connectivity profile. This guide focuses on implementation details.

Ownership is the critical boundary. The PMS or channel manager remains the source of truth for its operational model; Booking.com identifiers remain external identities; and the outbound projection is tracked separately from the reservation lifecycle received in return. Without those boundaries, successful HTTP calls can still produce wrong rates, closed rooms or double inventory adjustments.

Provider companion snapshot

Current authentication contract

New integrations should use token-based authentication:

machine-account client_id + client_secret
        |
        v
POST /token-based-authentication/exchange
        |
        v
short-lived access token (~1 hour)
        |
        v
Connectivity API calls

Credential-based authentication was sunset on 31 December 2025. Do not generate a token for every business request; cache it with an expiry margin and single-flight refresh.

Rate-limit contract

Booking.com's public Connectivity documentation lists a general limit of 10,000 calls/minute for all endpoints, with lower endpoint-specific limits. Examples include:

• /xml/reservationssummary: 700/min,
• selected OTA content/inventory notification endpoints: 75/min,
• token exchange: 30/hour per machine account.

Limits can change and Booking.com may impose account-specific limits. Use endpoint/account quota configuration rather than one hard-coded global assumption.

Polling / pagination boundary

Connectivity does not have one universal pagination model. Reservation/message retrieval can use queue semantics while other resource APIs can have endpoint-specific pagination. Do not force a generic page++ abstraction across the provider.

For reservation workers, the important controls are:

queue age
oldest unprocessed message
pull latency
persist latency
ack latency
duplicate delivery rate

Booking / reprice lifecycle boundary

The core Connectivity contract projects distribution state to Booking.com and returns reservation state. A generic metasearch search -> reprice -> book lifecycle does not apply here.

PMS/CM ARI
   -> Booking.com sellable state
   -> consumer booking on Booking.com
   -> reservation message
   -> durable persistence
   -> PMS/downstream processing
   -> acknowledgement

Separate Booking.com products such as Request to Book have their own versioned contracts and should not be collapsed into the generic Connectivity ARI flow.

Production scenario

Consider a production scenario in which the PMS closes a room-rate, changes its price seconds later, and receives a Booking.com modification at the same time. Out-of-order events can reopen inventory remotely, while acknowledging the reservation before durable persistence can lose the booking. The architecture below is designed to prevent that class of state drift.

What does the integration cover?

Depending on account access, the Connectivity family can support property onboarding, room types and rate plans, rates and availability (ARI), reservation delivery, and capabilities such as payments, messaging or promotions. Access is neither automatic nor uniform: machine-account properties, connection types, permissions, certification and compliance status determine the available surface.

Connectivity does not own:

• canonical property, room and rate identity inside your system,
• source-of-truth decisions between PMS and channel state,
• change detection and outbound ordering,
• duplicate reservation/event protection,
• drift detection and reconciliation,
• PII and payment security policy,
• inventory propagation to other channels.

How should access and authentication work?

Create machine accounts through the Connectivity Portal and authorize them for the relevant properties and connection types. Keep test and production accounts and property sets separate.

New implementations must use token-based authentication. Credential-based authentication was sunset on 31 December 2025. Generate short-lived tokens from machine-account credentials, cache them server-side and refresh with an expiry margin instead of attaching long-lived credentials to every business request.

Secret Store
    |
    v
Token Manager ----> short-lived token cache
    |                       |
    +-----------------------+
                            v
                    Connectivity Adapter

Do not make token generation part of every user-facing or batch call. Use a lock or single-flight mechanism when concurrent workers encounter expiry. Track AUTH_TOKEN_FETCH_FAILED, AUTH_TOKEN_EXPIRED and PROPERTY_NOT_AUTHORIZED separately.

What should the production flow look like?

PMS / Channel Manager
        |
        v
Canonical Hotel Model
        |
        +--> Change Detector --> Transactional Outbox
                                   |
                                   v
                              Booking Adapter
                                   |
          +------------------------+-------------------+
          |                        |                   |
          v                        v                   v
     Property/Product          Rates & ARI       Remote responses
          |                        |                   |
          +------------------------+-------------------+
                                   |
                                   v
                           Delivery Ledger

Booking Reservation Queue
        |
        v
Pull / Decode / Validate / Persist
        |
        +--> inventory and downstream events
        |
        v
Acknowledgement + Reconciliation

An accepted outbound request does not prove that remote business state matches the intended state. Retain the request, affected entities, response, RUID/correlation data and item-level semantic outcome in a delivery ledger.

How should canonical and Booking.com IDs be separated?

Do not use provider IDs as the only domain identity:

internal_property_id != booking_property_id
internal_room_type_id != booking_room_id
internal_rate_plan_id != booking_rate_id

A mapping model can include:

provider_properties
- internal_property_id
- provider_property_id
- connection_status
- credential_scope

provider_room_rates
- internal_room_type_id
- internal_rate_plan_id
- provider_room_id
- provider_rate_id
- pricing_type
- mapping_version

A room-rate is the commercial combination of a room type and rate plan. Updating by room ID alone loses meal-plan, cancellation-policy and booking-rule distinctions.

Why is the pricing model a migration decision?

Booking.com supports Standard, derived, Occupancy-Based Pricing (OBP), Length of Stay (LOS), and RLO behavior in relevant room-rate scenarios.

• Standard: sends a price for a defined occupancy.
• Derived: calculates occupancy prices using fixed or percentage offsets.
• OBP: requires absolute amounts by date, room, rate and occupancy.
• LOS: carries a matrix by check-in date, occupancy and number of nights.

Changing property pricing type can require prices, closures, restrictions and inventory to be defined again. Treat the change as a controlled migration:

1. pause outbound ARI,
2. snapshot current remote state,
3. build a complete projection for the new model,
4. verify it against a test property,
5. satisfy certification requirements,
6. recheck inventory and effective bookability.

Confirm current certification requirements for OBP, LOS and selected elements in the official go-live documentation before rollout.

What should the normalized ARI model contain?

The internal contract should not mirror one provider endpoint:

interface HotelDistributionUpdate {
  eventId: string;
  propertyId: string;
  roomTypeId: string;
  ratePlanId: string;
  dateFrom: string;
  dateTo: string;
  inventory?: number;
  open?: boolean;
  price?: {
    currency: string;
    amount: number;
    occupancy?: number;
    lengthOfStay?: number;
  };
  restrictions?: {
    minStay?: number;
    maxStay?: number;
    closedToArrival?: boolean;
    closedToDeparture?: boolean;
    minAdvance?: number;
    maxAdvance?: number;
  };
  sourceVersion: number;
  occurredAt: string;
}

Inventory, availability and restrictions are different concepts. A room-rate can have physical inventory and still be closed or fail a particular itinerary because of a minimum-stay rule.

Overlapping restrictions are a specific risk. Booking.com documents that conflicting or overlapping restrictions can make a room unavailable without returning an error or warning. A local preflight evaluator should calculate effective availability for representative stays before delivery.

How should full and delta synchronization coexist?

Use deltas for normal operation and bounded full synchronization for onboarding, mapping changes and drift recovery.

property + room + rate + date-range + change-type + source-version

An outbox flow should:

1. write the domain change and outbox event in one local transaction,
2. translate the event into a provider projection,
3. validate schema and business preconditions locally,
4. send it to Booking.com,
5. record the delivery outcome,
6. retry transient failure or route permanent rejection to a dead-letter workflow.

Preserve ordering by entity and date window. An older open=true event applied after a newer closed=true event is transport-valid but commercially wrong.

Which data is durable and which is ephemeral?

Persist durably

• canonical-to-provider mappings,
• property, room and rate configuration versions,
• pricing type and currency,
• outbound events and delivery ledger,
• provider result codes and RUID/correlation references,
• reservation IDs, revisions, statuses and lifecycle events,
• acknowledgement outcomes,
• reconciliation snapshots and discrepancies.

Treat as ephemeral or secret

• access tokens,
• raw machine-account credentials,
• unmasked card and PII fields,
• reservation acknowledgement tokens,
• temporary cursors and worker locks.

If raw payloads are needed for support, use encrypted, access-controlled storage with limited retention. Never put payment-card data or unnecessary PII in general application logs.

How should reservation delivery become idempotent?

The Reservations API queues new booking, modification and cancellation messages. In the OTA flow, messages may be returned repeatedly until acknowledged; duplicate delivery is normal. B.XML has no separate acknowledgement step and assumes the provider can process a successfully retrieved response.

Pull message
    |
    v
Persist raw envelope + reservation revision
    |
    v
Idempotent business processing
    |
    +--> inventory adjustment
    +--> PMS/downstream event
    |
    v
Acknowledge only after durable acceptance

Reservation ID alone may not be sufficient as a deduplication key; modification/cancellation sequence or response-token data can represent the revision. Replay must not create a second booking, cancellation or inventory decrement.

Booking.com may send a fallback email to the property when a creation, modification or cancellation is not successfully acknowledged or retrieved within the default 30-minute window. Monitor this as an operational SLO; email fallback is not a successful integration path.

How should freshness and reconciliation work?

Measure three kinds of freshness:

• source freshness: age of the PMS change,
• delivery freshness: delay until provider acceptance,
• remote-state freshness: age of the last read-back or reconciliation.

Periodic reconciliation should sample or compare:

• connected and active property state,
• room-rate mappings and pricing types,
• forward inventory and closure windows,
• rate and restriction projections,
• unacknowledged and recently changed reservations,
• rejected or long-pending updates.

When drift is found, do not immediately overwrite the whole property. Classify the discrepancy, determine the authoritative side and issue a scoped repair event.

What should the error and retry policy look like?

AUTH_TOKEN_FAILED
AUTH_SCOPE_DENIED
PROPERTY_NOT_CONNECTED
SCHEMA_INVALID
MAPPING_MISSING
PRICING_MODEL_MISMATCH
BUSINESS_RULE_REJECTED
RATE_LIMITED
PROVIDER_5XX
PROVIDER_TIMEOUT
UPDATE_STATE_UNKNOWN
RESERVATION_DECODE_FAILED
RESERVATION_ACK_FAILED
RECONCILIATION_DRIFT

Network failures, selected 5xx responses, rate limits using server guidance, and idempotent reads or pulls may receive bounded retries. Schema failures, missing mappings, unauthorized properties, pricing conflicts and business rejections should not be retried blindly.

No response does not mean the update was not applied. For an unknown outcome, investigate with correlation/RUID data or read state back instead of sending the same payload indefinitely.

Booking.com's reservation guidance allows a broad client timeout for pull and OTA acknowledgement calls. Do not copy that value into user-facing HTTP paths. Run reservation workers in a separate resource pool with bounded concurrency and a queue-age SLO.

Which failure modes matter?

Out-of-order deltas

An older event reverses newer inventory or closure state. Require source versions and entity-level serialization.

Mapping drift

A room or rate is recreated while local mapping still points at the old provider ID. Monitor silent projection gaps as well as explicit rejection.

Restriction collision

Individually valid restrictions jointly make a room-rate unsellable. Run synthetic stay tests.

Partial batch acceptance

Transport succeeds while some items fail. Record semantic status per item.

Premature acknowledgement

Acknowledging before durable processing can permanently lose a booking after a crash.

Duplicate delivery

Acknowledgement delay causes redelivery. Deduplication must be a normal path, not an exceptional repair.

What should be monitored?

Authentication and access

• token refresh success/failure,
• authentication rejection by machine account,
• unauthorized-property count,
• token age and expiry margin.

Outbound synchronization

• update lag p50/p95,
• accepted/rejected item rate,
• pending outbox age,
• retry and dead-letter volume,
• missing-mapping rate,
• ARI coverage horizon.

Reservation delivery

• oldest unprocessed-message age,
• pull-to-persist and persist-to-ack latency,
• duplicate delivery rate,
• acknowledgement failures,
• fallback-email risk-window breaches,
• modification/cancellation processing lag.

Business quality

• overbooking incident rate,
• unexpectedly closed room-rate count,
• price/restriction drift,
• reconciliation-gap age,
• effective bookability coverage by property and room-rate.

An HTTP 2xx rate is not provider health. Item-level acceptance, queue freshness and effective bookability must be visible together.

Go-live checklist

• Are machine-account scope and property connections verified?
• Is token authentication expiry-aware and single-flight?
• Are test and production credentials and properties separate?
• Are canonical property, room and rate IDs independent of provider IDs?
• Are pricing type and certification scope explicit?
• Are room-rate, occupancy, tax, meal and cancellation semantics retained?
• Are delta ordering and a transactional outbox implemented?
• Is payload and effective-restriction preflight validation in place?
• Are partial batch outcomes processed per item?
• Are reservations acknowledged only after durable persistence?
• Have duplicate modification and cancellation replays been tested?
• Are queue age and fallback-email risk monitored?
• Is retry behavior based on error class and operation idempotency?
• Do remote/local reconciliation and scoped repair work?
• Are PII/payment masking and retention policies enforced?
• Are certification, self-assessment and beta rollout complete?

Meta Search takeaway

Booking.com Connectivity is not a metasearch shopping API; it projects source distribution state into the Booking.com channel and returns reservation state. It still affects metasearch quality upstream: preserving room, rate, occupancy, restriction and price semantics produces more comparable offers downstream. Judge the integration by explainable, reconciled agreement between local truth and remote bookability—not by request volume.

Companion capability boundary

Booking.com Connectivity is a family of distribution and reservation contracts, not one universal API. Property/product setup, ARI projection, reservation retrieval and optional payments/messaging capabilities should remain separate adapter concerns.

Observability

Monitor source-to-provider update lag, item-level rejection, oldest reservation-message age, persist-to-ack latency, duplicate delivery, reconciliation drift and effective bookability. HTTP success rate alone is not sufficient health evidence.