Integration guide

The Booking.com API: how access works, and what it actually lets you do

Written for the engineer or technical founder pointed at Booking.com's Connectivity APIs. It covers how partner designation and per-property connection work, the data model that everything else depends on, and the two or three behaviours that make a Booking.com rate update succeed on paper and change nothing in practice.

What the Booking.com API is

Booking.com's APIs are built for connectivity providers: the channel managers and property management systems that keep accommodation in sync on behalf of many properties at once. They are not consumer APIs, there is no public search or booking surface for third parties, and there is no developer portal you sign up to.

Practically it is several product surfaces under one partnership — availability and rates, reservations, property and room setup, content, messaging, reviews, and financial charges. They behave differently from one another, they are entitled separately, and parts of the older surface are XML rather than JSON. Coming from Airbnb, almost none of your assumptions transfer.

How do I get Booking.com API access?

Three layers, granted by three different parties, exactly as with Airbnb but shaped differently.

1. Booking.com designates your company a connectivity partner. You apply, you are reviewed commercially and technically, and there is a certification step against the surfaces you intend to use. This is a company-level relationship measured in months.
2. You are issued credentials for a machine account.Unlike Airbnb's per-host OAuth tokens, one machine account acts for every property connected to you. That single credential is the blast radius for your whole book of business, and it changes how you read errors — see the note below.
3. Each property connects you from its own Extranet. The host signs in to the Booking.com Extranet, opens the connectivity provider list, finds your provider by name, and clicks Connect. Until they do, your machine account cannot see that property at all. They will also need their numeric Hotel ID to hand.

Through Repull the host-facing half is one hosted session that carries your branding; they complete the Extranet step and paste their Hotel ID, and you get a connection back. The walkthrough is on Connect Booking.com.

curl -X POST 'https://api.repull.dev/v1/connect/booking' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "redirectUrl": "https://yourapp.com/connected" }'

Properties, rooms and rate plans

Get this right and the rest of Booking.com follows. Get it wrong and every endpoint feels arbitrary.

Booking.com property   "hotel_id": 5432505        ← the building
└── room               "roomBookingId": 543250501 ← what a guest books
    └── rate plan      "rateId": 98765            ← the terms it sells on
        └── price at an occupancy                ← what you actually write

A property is a building. Rooms are what guests book. Rate plans are the commercial terms a room sells on, and a price belongs to a (room, rate plan, date, occupancy) tuple — not to a night. A one-bedroom villa is the simple case; a twenty-unit aparthotel is a single property holding twenty rooms, which is normal rather than an edge case.

The same unit can also appear under more than one Booking.com property, usually because it was re-listed over time, and a room that has not been mapped to one of your listings belongs to nothing — its reservations have nowhere to land. Map rooms during the connect flow, not afterwards.

Can I update rates through the Booking.com API?

Yes, and this is the most-used surface in the whole partnership. You write a price for a room on a rate plan over a date range, optionally with length-of-stay and arrival restrictions in the same call.

curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "rates",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "price": 210,
      "currency": "USD",
      "occupancy": 4
    }]
  }'

roomId and rateId come from GET /v1/channels/booking/properties/{id}/rooms. Everything else on the request — and there is more of it than you expect — is on Update Booking.com pricing.

Why did my Booking.com price update do nothing?

This is the question that brings people to this page, and there are two independent answers. Both look like success.

The occupancy is part of the key, not a preference

Booking.com does not store “the price of this night”. It stores a price for a night at a party size on one rate plan. So the occupancy you send decides which price you are overwriting. Every rate amount goes out against one, whether you named it or not.

• Name an occupancy above the maximum the rate plan itself prices at, and Booking.com accepts the request and declines the amount without saying so. The night keeps whatever it held before — often 0.00 — and the acknowledgement is byte-identical to a successful write.
• Name one below it and you get a 400. The published price does not change.
• The guest capacity on your own listing is not the input. The number that governs is the one Booking.com holds for that rate plan. Read it back rather than inferring it.

Repull resolves the occupancy from Booking.com's own data for the (room, rate plan) pair when you omit it, echoes both the value used and where it came from, and refuses the write with a 422 when it cannot be resolved. A rate amount is never sent blind.

The acknowledgement is not a confirmation

Booking.com usually answers a rate write with a bare acknowledgement carrying no per-date status. The body is literally:

{"ok": ""}

Date ranges, and the night you lose

Underneath, the availability and rates XML takes a range whose to date is not written— it is an exclusive bound, the way a checkout date is exclusive of the last night. Most calendar surfaces you will have integrated before treat both ends as nights. So the natural reading of “1 to 7 August” is seven nights and the wire meaning is six, and the night you silently drop is the last one of every range you write.

It is a one-line conversion and a week-long bug, because it only ever costs you the final night: the calendar looks broadly right, a spot check passes, and the gap shows up as a missed booking rather than an error.

Inventory is a separate write

Pricing a night does not open it for sale, and opening it does not price it. Rooms to sell and the stop-sell flag are their own update type; sending them on a rate update is refused rather than silently dropped.

# Close a night: zero rooms to sell, stop-sell on
curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "availability",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "availableRooms": 0,
      "closed": true
    }]
  }'

Detail on Push availability to Booking.com. If you would rather write a calendar once and have it land on every connected channel, that is PUT /v1/availability/{propertyId}, with PATCH /v1/availability/batch for many properties at once.

Restrictions that exist, and ones that do not

Minimum and maximum stay (both stay-date and arrival-date based), closed to arrival and closed to departure are all real and settable per room, rate plan and date range.

Several restrictions people expect are simply not in the notification Booking.com accepts — an exact stay length on arrival, and minimum or maximum advance reservation among them. The right behaviour is to refuse them loudly. A restriction that is accepted and then not sent is the one failure you cannot see in a response, so Repull answers 422 naming the field rather than dropping it. See restriction_not_supported and Minimum stay and restrictions.

Reservations, messaging, reviews and charges

• Reservations — list them, and acknowledge them. The acknowledgement is not optional bookkeeping: new reservations sit in a queue until you clear them, and a partner that never acknowledges keeps re-reading the same bookings. Reservations.
• Messaging— list conversations and send. Narrower than Airbnb's thread surface; there is no edit, no reaction, no read-state. Guest messaging.
• Reviews — list and reply. Reviews.
• Charges and fees — read and write. Charges and fees.
• Setup and go-live — creating the legal entity, checking readiness, setting contacts and policies, and opening a property for sale. Setup and go live.
• No alterations.Booking.com has no equivalent of Airbnb's alteration flow. Date and price changes on an existing booking are not an API operation.

The capability matrix sets Airbnb and Booking.com side by side, marking partial as partial rather than rounding it up.

Why does the Content API return 403?

Because content is its own product surface with its own entitlement, on its own base path, separate from the availability, rates and reservations surfaces. A property can be fully live — taking bookings, accepting every rate and availability write you send — while every content call for that same property answers 403.

When that happens, the instinct is to suspect the token, then the property id, then the host's Extranet permissions. It is usually none of those. The capability was not granted to you for that surface, and no amount of reconnecting changes it. Confirm which capabilities your partnership actually carries before you scope photo or description management into a release.

Content itself, where it is available, covers photos, descriptions, amenities, facilities and policies, at property or room level — and Booking.com reviews text changes before they appear, so a write is the start of a process rather than the end of one. Content and photos.

What it takes to build this yourself

1. Partner designation and certification. Months, with commercial review and a technical certification step per surface. You cannot promise a customer a date.
2. A shared-credential security model. One machine account for every property you serve. Rotation, storage, and an error classifier careful enough that a global 401 during an outage cannot mass-disconnect your customers.
3. The model and the mapping. Properties to rooms to rate plans to your own listings, including multi-room properties, re-listed units, and unmapped rooms whose reservations have nowhere to go.
4. Write verification. Because the acknowledgement proves nothing, a correct integration reads back and reconciles. That is an extra call, a settle delay and a state machine, on the hottest path you have.
5. Convention mismatches. Exclusive date bounds, occupancy-keyed prices, inventory split from rates, restrictions that do not exist, XML where you expected JSON.
6. Ongoing breakage. Same as every partner API: it does not converge to zero.

The honest summary is that Booking.com is a heavier integration than Airbnb and shares almost none of its assumptions — different auth model, different data model, different date semantics, different definition of a successful write. Teams that have just finished Airbnb consistently underestimate it. The Airbnb API guide is the comparison.

Where Repull fits

Repull is one REST API and one key across Booking.com, Airbnb, VRBO, Plumguide and 50+ property management systems. We hold the partner relationships; properties connect themselves through a hosted flow that carries your branding.

• One hosted connect flow. POST /v1/connect/{provider}, with room mapping handled inside it. Connect.
• Writes that tell you the truth. Read-back verification on rates, occupancy resolved and echoed, unsupported restrictions refused rather than dropped, inclusive date ranges at both ends.
• One calendar write for every channel. PUT /v1/availability/{propertyId} pushes price and availability to every channel a property is connected to.
• Webhooks with delivery history and replay, rather than per-channel notification plumbing. Webhooks.

Start at the quickstart, or read the channels overview. If you are a platform embedding this for your own customers rather than integrating for yourself, the guide for platforms covers that model question by question.

Frequently asked questions