Live demo

Hotel supplier integration

Hotelbeds API integration: content, mapping and live booking

A Hotelbeds API integration is two jobs, not one. You download and store hotel content, then you book against live rates. PHPTRAVELS does both inside its hotel module, with your own Hotelbeds contract and keys.

  • Content API sync
  • Booking API flow
  • BOOKABLE and RECHECK rates
  • Hotel mapping

How the Hotelbeds APIs fit together

Hotelbeds API integration: content on one side, booking on the other

Hotelbeds splits its hotel APIs in two. The Content API returns static data: descriptions, images, facilities, boards and rooms. The Booking API returns live availability and prices and takes the booking. Pick a step in the middle to see which calls it uses.

Content API

Static, stored on your side
  • Hotel listhotels · from=1&to=1000Every hotel in your portfolio, in pages of up to 1,000 hotels per request.
  • Facilities, boards and roomsfacilities · boards · roomsThe code tables that turn Booking API codes into words your guests understand.
  • Imagesphotos.hotelbeds.com/giata/Partial image paths, joined to the Hotelbeds photo host in the size you need.
  • Daily changeslastUpdateTimeAfter the first load, one request a day with lastUpdateTime returns only what changed.

Request flow

Booking API

Live, called per guest
  • AvailabilityPOST /hotelsRooms, boards, prices and cancellation fees for your hotel codes, dates and occupancy.
  • Check ratePOST /checkratesUpdated price and conditions for a rate marked RECHECK, plus upselling options.
  • BookingPOST /bookingsConfirms the chosen rateKey with the holder and guest names, and returns the reference.
  • CancellationDELETE /bookings · simulateSimulates a cancellation to show the fee, or cancels the booking for real.
Sample screen. Calls as documented on developer.hotelbeds.com; the flow is how PHPTRAVELS uses them.

Most failed Hotelbeds projects mix the two sides up. They call the Content API during a guest search, which is slow and, as Hotelbeds warns, can get your credentials blocked. Or they search live without stored codes and cannot show images or facilities. PHPTRAVELS keeps the two apart: content is synced in the background, and only availability, check rate and booking calls run while a guest waits.

If you want the supplier itself, its products and how to open an account, read the Hotelbeds supplier profile. This page is about the technical integration.

Rate types

The four rate fields that change your checkout

Every Hotelbeds rate carries a few attributes that decide whether you can book it straight away, what price you may show and who takes the money. These are the ones your engine must read on every result.

FieldFirst caseSecond caseWhat PHPTRAVELS does

Bookable or recheck

rateType		BOOKABLE

The rate is up to date. You can book it without another call.

RECHECK

You must call check rate first to get the updated price and conditions.

Runs check rate before the payment step for RECHECK rates and shows the guest any change.

Net or commissionable

net · sellingRate		net

Net model: prices are net, so you add your own margin.

sellingRate

Commissionable model: the commission is already inside sellingRate, and that price is final.

Applies your markup rules to net rates and sells commissionable rates at sellingRate.

Fixed selling price

hotelMandatory		true

hotelMandatory is true: you must sell at sellingRate.

false · null

False or empty on a net rate: you may set your own margin.

Locks the displayed price to sellingRate when the hotel requires it, whatever the markup rule says.

When the guest pays

paymentType		AT_WEB

Payment is taken when the booking is made, through your site.

AT_HOTEL

The guest pays the hotel directly.

Labels the rate pay now or pay at hotel, and routes checkout to match.

Which pricing model you get depends on your Hotelbeds contract. As Hotelbeds states, your sales manager recommends the model for your business.

Hotel mapping

Match Hotelbeds hotels to the hotels you already sell

If you have your own contracts or a second supplier, the same hotel will arrive under different codes. Mapping links them, so a guest sees one hotel with the best rate, not three copies.

How mapping works in PHPTRAVELS

After each content sync, PHPTRAVELS compares Hotelbeds hotels with your hotel list by name, address, city and coordinates. Close matches are linked automatically. Doubtful ones wait for a person to confirm, and hotels with no match can be imported as new properties or ignored.

Mapped hotels share one page, one gallery and one review score in the Stays, while each supplier keeps its own rates and rules. The same mapping is used by your public site and your B2B travel portal.

Hotel mapping
  • Harbour View HotelLisbon48291397%Matched
  • Old Town SuitesPrague11735492%Matched
  • Palm Court ResortDubai66201874%Review
  • Casa Azul BoutiqueSeville–0%No match
  • Northern Lights LodgeTromsø90522766%Review
  • Riverside ApartmentsBudapest33076198%Matched

Sample screen with made-up hotels and codes.

Hotelbeds XML or JSON

Every request is signed, and testing starts small

Teams still search for Hotelbeds XML, but the current documentation shows JSON requests. Either way it is the same set of operations, and each request carries two headers.

availability-request.sh (sample)
 1# X-Signature = SHA256(api key + secret + unix time in seconds) 2TS=$(date +%s) 3SIG=$(printf "%s%s%s" "$API_KEY" "$SECRET" "$TS" | sha256sum | cut -d" " -f1) 4 5curl -X POST https://api.test.hotelbeds.com/hotel-api/1.0/hotels \ 6  -H "Api-key: $API_KEY" \ 7  -H "X-Signature: $SIG" \ 8  -H "Accept: application/json" \ 9  -H "Content-Type: application/json" \10  -d '{11    "stay": { "checkIn": "2026-11-14", "checkOut": "2026-11-17" },12    "occupancies": [{ "rooms": 1, "adults": 2, "children": 0 }],13    "hotels": { "hotel": [482913, 117354] }14  }'1516# hotel codes come from your stored Content API data, never a live content call
Api-keyX-Signatureapi.test.hotelbeds.com
Two headers
Api-key with your key, and X-Signature: a SHA256 hash of your key, your secret and the current time in seconds.
Test host
As Hotelbeds states, the test servers match production, but bookings there are not real and cards are not charged.
50 requests a day
New keys open an evaluation environment with a quota of 50 requests a day. More comes with certification.
No live content calls
Hotelbeds warns that calling the Content API in real time can get credentials blocked. PHPTRAVELS never does.

Content sync planner

How many Content API calls your hotel list needs

As Hotelbeds states, the hotel list comes in pages of up to 1,000 hotels, and after the first load a daily lastUpdateTime request returns only the changes. Enter your numbers to plan the sync.

Requests for the first full load
20
Requests per daily update
3
Days to load once on the evaluation quota
1

Estimate only, for the hotel list. Code tables and images add a few more calls. On the evaluation quota of 50 requests a day, test with one destination first.

Go-live checklist

What to have ready before you switch to live

Hotelbeds moves you from evaluation to certification and then to live keys through its dashboard. These are the points a Hotelbeds API integration should cover first, and how PHPTRAVELS covers them.

  • Evaluation keys added in the admin, test host selected
  • Content API synced to your database, with a daily update scheduled
  • Hotels mapped to your list, doubtful matches reviewed
  • RECHECK rates go through check rate before payment
  • sellingRate respected when hotelMandatory is true
  • Rate comments and cancellation fees shown before the guest pays
  • Voucher shows the Hotelbeds reference and the rate comments
  • Cancellation simulated first, then confirmed, with the fee recorded

Certification steps and live access are set by Hotelbeds for your contract and market.

Cost

One licence for the engine, your own contract with Hotelbeds

PHPTRAVELS is a one-time licence with the source code. Hotelbeds is a separate agreement between you and Hotelbeds, so the net rates and the keys stay yours.

Startup
$2,499
one-time licence
Agency
$4,999
one-time licence
Enterprise
$9,999
one-time licence

Hotelbeds is one of several hotel sources you can run side by side. See how it sits with RateHawk in the travel APIs overview, or compare suppliers in the XML supplier list.

See pricingTry the hotels demo

FAQ

Hotelbeds API integration questions

What developers and travel companies ask before they connect Hotelbeds.

Talk to sales

Two parts. A background sync with the Content API that stores hotels, images, facilities, boards and rooms in your database, and a live flow with the Booking API for availability, check rate, booking and cancellation. PHPTRAVELS runs both in its hotel module.

People still call it Hotelbeds XML, but the current Hotelbeds documentation shows JSON requests and responses. The operations are the same either way, and PHPTRAVELS handles the format for you.

A BOOKABLE rate is already up to date and can be booked straight away. A RECHECK rate needs a check rate call first, which returns the current price and conditions. PHPTRAVELS makes that call before the payment step.

It is slow, and Hotelbeds warns that using the Content API in real time can lead to blocked credentials. Content should be downloaded in pages, stored, and updated once a day with lastUpdateTime, which is how PHPTRAVELS works.

Yes. You register with Hotelbeds, sign the contract and receive your own API key and secret. New keys work on an evaluation environment with 50 requests a day until you complete certification.

Yes. Hotel mapping links the same property across sources, so guests see one hotel with the best available rate, while each source keeps its own markup and rules.

PHPTRAVELS plans start at $2,499 as a one-time licence with the source code. Your Hotelbeds contract is separate and agreed directly with Hotelbeds. See the pricing page or ask sales for a quote.

Keep exploring

More from the platform