generated: '2026-09-17'
method: derived
source: >-
  Derived from the 20 OpenAPI descriptions in openapi/ (retrieved from Booking.com's own docs MCP server
  2026-09-17) and searched against the Demand API development guide at
  https://developers.booking.com/demand/docs/development-guide/.
docs:
- https://developers.booking.com/demand/docs/development-guide/rate-limiting
- https://developers.booking.com/demand/docs/support/error-handling/about-errors
- https://developers.booking.com/demand/docs/development-guide/authentication
- https://developers.booking.com/connectivity/docs/deprecation-policy/deprecation-and-sunsetting
name: Booking.com cross-cutting API conventions
summary: >-
  Booking.com runs two conventions regimes. The Demand API is a POST-only JSON RPC-over-HTTP surface -
  every one of its 32 operations is a POST, including pure reads such as /accommodations/search and
  /common/languages - with a bearer token plus an X-Affiliate-Id header, a request_id echoed on every
  error, and no idempotency mechanism. The Connectivity APIs are a more conventional REST surface over
  supply-xml.booking.com with JWT auth, mixed JSON and OTA/B.XML payloads, and a formal published
  deprecation and sunset policy.
auth_style:
  demand: 'Authorization: Bearer <key> plus X-Affiliate-Id: <aid> on every request'
  connectivity: 'Authorization: <JWT>, one-hour lifetime, minted from machine-account credentials'
  see: authentication/booking-com-authentication.yml
http_style:
  demand:
    verbs: [POST]
    detail: >-
      All 32 published Demand API 3.2 operations are POST, reads included. Parameters travel in the JSON
      request body, not the query string, so responses are not cacheable by HTTP semantics and an agent
      cannot construct a GET for any Booking.com Demand resource.
  connectivity:
    verbs: [GET, POST, PUT, PATCH, DELETE]
    detail: Conventional REST across rooms, property, facilities, charges, payments and reconciliation.
  connect_api:
    verbs: [GET, POST]
idempotency:
  coverage: none
  scope: []
  mechanism: null
  header: null
  retention: null
  detail: >-
    No idempotency mechanism exists on any Booking.com write surface. There is no Idempotency-Key header,
    no client-supplied request key, and no documented replay behaviour, on either the Demand API order
    operations (/orders/create, /orders/modify, /orders/cancel) or the Connectivity write operations.
    The only occurrence of the word in all 20 specs is in the Payments by Booking Onboarding API, where
    request_id is described as "the idempotency key of the latest accepted configuration change request"
    - that is a SERVER-generated identifier reported back in a status response, not a client-supplied
    key, so it cannot be used to make a retry safe. An agent retrying a timed-out /orders/create has no
    protocol-level way to avoid creating a second booking.
  evidence:
  - openapi/booking-com-demand-api-3-2-openapi.yml
  - openapi/booking-com-payments-by-booking-onboarding-api-openapi.yml
reversibility:
  grade: verified
  detail: >-
    Every Demand API write has a first-class reversal, and the window is machine-readable rather than
    merely stated in prose.
  surfaces:
  - write: /orders/create
    reversal: /orders/cancel
    operationId: /orders/cancel
    window: >-
      Per-product, and returned in the contract. productDetailedCancellationPolicyMultiCurrency is a
      cancellation-fee schedule whose entries each carry a `from` ISO 8601 date-time (or the literal
      "now") and the fee that applies from that moment. A client reads the free-cancellation deadline and
      the fee steps off the availability, details and order responses before it books.
    docs: https://developers.booking.com/demand/docs/orders-api/cancel-order
    constraints:
    - Only one travel service can be cancelled per request.
    - >-
      Accommodation cancellations complete immediately; car rental and car insurance cancellations
      continue asynchronously after a 200.
    - >-
      409 is returned when the travel service is not eligible for cancellation in its current state -
      already cancelled, or no longer cancellable.
    - /orders/cancel for cars is not available in the sandbox (403 sandbox_blocked).
  - write: /orders/create
    reversal: /orders/modify
    operationId: /orders/modify
    window: >-
      Governed by the same cancellation policy schedule; 3.2-Beta adds /orders/modify/preview so an agent
      can price a modification before committing it.
  - write: Connectivity write operations (rooms, rates, facilities, charges, property)
    reversal: null
    window: null
    note: >-
      These are declarative state-setting operations - a later call overwrites the earlier state - rather
      than transactional ones, so there is no undo operation and none is needed. Not graded.
dry_run_mode:
  available: partial
  detail: >-
    /orders/preview (3.2) and /orders/modify/preview (3.2-Beta) let a client rehearse an order and a
    modification and see the resulting price before committing. There is no dry-run on any Connectivity
    write.
pagination:
  style: page-size parameter, no cursor
  params:
  - name: rows
    detail: Controls how many results are returned per page on list-shaped Demand API endpoints.
  response_fields: []
  note: >-
    Booking.com documents `rows` as the pagination control in the rate-limiting guide. No Link header,
    cursor token or total-count field is documented as a general convention.
field_expansion:
  mechanism: extras
  detail: >-
    /accommodations/search and /accommodations/details take an `extras` array naming the additional
    blocks to return - description, facilities, payment, photos, policies, rooms. This is Booking.com's
    sparse-fieldset equivalent, and the docs present it as the primary payload-size control.
metadata:
  detail: >-
    Connectivity JSON responses wrap payloads in a `meta` / `data` / `errors` / `warnings` envelope
    (DefaultMeta). No customer-defined metadata field is offered on any object.
request_id_tracing:
  available: true
  field: request_id
  location: response body
  detail: >-
    Demand API error responses carry a top-level request_id (ULID-shaped, e.g.
    01kjan7r7yvff5yg95gxy1cjhy) alongside the errors array. It is a body field, not a response header,
    so it cannot be read from a failed request without parsing the body.
versioning:
  style: URL path segment
  detail: >-
    Demand API versions live in the path - /3.1, /3.2 - and each version is published as its own OpenAPI
    document. A 3.2-Beta track runs at the same /3.2 host path and carries attractions, transfers, smart
    search, messaging and car availability ahead of GA. Connectivity endpoints version individually
    (OTA_HotelProductNotif 1.0/1.1/1.2, rooms 1.2/1.3) and are retired on the published deprecation
    timeline.
  see: lifecycle/booking-com-lifecycle.yml
error_envelope:
  format: custom
  rfc9457: false
  shape:
    request_id: string
    errors:
    - id: string
      message: string
  connectivity_shape:
    meta: object
    data: object
    errors: array
    warnings: array
  detail: >-
    No application/problem+json anywhere in the 20 specs. The Demand API uses {request_id, errors[]} with
    a machine-readable string id per error (for example sandbox_blocked); Connectivity JSON APIs use the
    meta/data/errors/warnings envelope. Both are stable and parseable but neither is RFC 9457.
  see: errors/booking-com-problem-types.yml
rate_limit_signaling:
  status: 429
  headers_published: false
  retry_after: Declared only on the Reconciliation API 429 response, as an int32 seconds value.
  see: rate-limits/booking-com-rate-limits.yml
content_types:
  json: application/json
  xml:
    detail: >-
      A large part of the Connectivity estate is XML - B.XML and OpenTravel Alliance (OTA 2003B) messages
      over HTTP POST - rather than JSON. The Value Adds Catalog API content-negotiates between JSON and
      XML on the Accept header.
cross_links:
  errors: errors/booking-com-problem-types.yml
  lifecycle: lifecycle/booking-com-lifecycle.yml
  authentication: authentication/booking-com-authentication.yml
  rate_limits: rate-limits/booking-com-rate-limits.yml
  sandbox: sandbox/booking-com-sandbox.yml