Live demo

Accommodation API

A Stays API for hotels, apartments and vacation rentals

A stays API carries every kind of accommodation to your booking site: hotel rooms, serviced apartments, holiday homes, hostels and guesthouses. This page explains the data behind a stay, the rules that make rentals different from hotels, and how PHPTRAVELS sells your own properties and supplier stock in one search.

  • Property, unit, rate, calendar
  • Minimum stays and fees
  • Cancellation windows
  • Own stock plus API supply

The data model

Four layers inside every stay

Whether it is a 300-room hotel or a single beach house, an accommodation API describes it in the same four nested layers. Each layer answers a different question a guest asks before booking.

01Property

The place itself: name, type, address and map position, photos, amenities, star or quality rating, house rules and check-in times.

property_id · type · address · geo · photos · amenities · check_in_from

02Room or unit

What is actually booked: a room type, a whole apartment or a bed in a dorm, with its size, beds and maximum occupancy.

unit_id · beds · size_m2 · max_adults · max_children

03Rate plan

How that unit is sold: the board, the cancellation policy, payment terms and who may book it, such as public or agent-only.

rate_plan_id · board · cancel_policy · payment · channel

04Availability

One row per night: the price, units left, minimum stay and whether arrival or departure is allowed that day.

date · price · units_left · min_stay · closed_to_arrival

A building, a room, a rate tag and a calendar drawn as separate stacked layers of one accommodation listing

PHPTRAVELS calls its accommodation module Stays because the same model covers far more than hotels. A property holds units, a unit is sold through one or more rate plans, and each rate plan has a night-by-night calendar of price and availability. Get these four layers right and a hostel bed, a hotel suite and a three-bedroom villa all fit the same search and checkout.

Suppliers name the layers differently, and some merge two of them, but the structure is always there. The Stays maps every source to it, so the guest sees one consistent page.

Night by night

The availability calendar is where stays are won or lost

Every stays API ends in a calendar. The search only returns a property when every night of the requested stay is open, priced and allowed by the stay rules.

Two-bedroom apartment · Standard rateNovember 2026 · Price per night
  1. 26
  2. 27
  3. 28
  4. 29
  5. 30
  6. 31
  7. 1120
  8. 2120
  9. 3
  10. 4
  11. 5
  12. 6165
  13. 7140
  14. 8120
  15. 9
  16. 10
  17. 11
  18. 123+165
  19. 13165
  20. 14140
  21. 15120
  22. 16120
  23. 17120
  24. 18
  25. 19
  26. 20165
  27. 21140
  28. 22120
  29. 23120
  30. 24120
  31. 25120
  32. 263+165
  33. 27165
  34. 28140
  35. 29120
  36. 30120
  37. 1
  38. 2
  39. 3
  40. 4
  41. 5
  42. 6
  • Open, priced per night
  • Already booked
  • Closed by the owner
  • Minimum stay from this arrival
  • Closed to arrival

Illustrative data, simplified

  • Prices are per nightThe stay total is the sum of each night, so a Friday and Saturday at weekend rates cost more than two weekdays. Day and seasonal prices live on the calendar, not on the property.
  • Minimum stay rulesA three-night minimum on a Friday arrival hides the unit from a two-night search. Rentals use these rules far more than hotels, often stricter at weekends and in high season.
  • Closed to arrival or departureA night can be bookable as part of a longer stay but not as its first or last night. Changeover days for holiday homes work this way.
  • Closed nights and stop-sellOwners block dates for their own use or maintenance, and a stop-sell takes a unit off sale at once. Any closed night inside the requested dates removes the unit from the results.

Not every stay is a hotel

Hotels vs apartments vs vacation rentals

The data model is shared, but each kind of stay fills it differently. These are the differences your booking flow has to handle when you sell more than hotel rooms.

Hotels

Including hostels and guesthouses

What is booked
A room type with many identical rooms, or a bed in a shared dorm.
Pricing
A nightly rate per room and board; extra adults or children may change it.
Stay rules
Minimum stays at peak dates only; most nights can be booked alone.
Fees and deposits
City or tourist tax, sometimes a resort fee paid at the property.
Arrival
A 24-hour or staffed front desk; check-in times on the voucher are enough.
Typical source
Bedbanks and wholesalers, direct contracts, channel managers.

Serviced apartments

Aparthotels and city apartments

What is booked
A unit type, often with a kitchen and separate bedrooms.
Pricing
A nightly rate per unit, with weekly or monthly prices for long stays.
Stay rules
Minimum stays are common, and long stays are a large part of demand.
Fees and deposits
A cleaning fee per stay and a refundable deposit are common.
Arrival
Reception hours vary; late arrivals need a key box or code.
Typical source
Channel managers, direct contracts and some wholesalers.

Vacation rentals

Holiday homes, villas and cabins

What is booked
One specific home. There is usually only one of it.
Pricing
A nightly rate for the whole home, plus a charge per extra guest above a base number.
Stay rules
Minimum stays, fixed changeover days and closed-to-arrival dates are the norm.
Fees and deposits
Cleaning fee, refundable damage deposit and local taxes, each shown before payment.
Arrival
Check-in instructions, an address and a contact are sent before arrival, never on the public page.
Typical source
Owners and property managers, directly or through a channel manager.

Selling homes from many hosts rather than your own contracts? That is a marketplace, covered on the BnB portal page.

Cancellation policy windows

One booking, three windows of cancellation

A cancellation policy is a timeline counted back from the arrival date. Each window says what the guest gets back if they cancel inside it.

BookingCheck-in
  1. 01 · Until 14 days before arrivalFree cancellationThe guest cancels and is refunded in full. This is the deadline travellers look for first, so show it as a date, not a rule.
  2. 02 · 14 to 3 days beforePartial penaltyA penalty applies, often the first night or a percentage of the stay. Rentals may keep the deposit inside this window.
  3. 03 · Last 3 days and no-showNon-refundableThe full amount is kept. Rate plans sold as non-refundable start in this window from the moment of booking.
Example windows; every rate plan carries its own.
  • Per rate plan, not per propertyThe same apartment can have a flexible rate and a cheaper non-refundable one, so the policy belongs to the rate plan layer.
  • Dates in the property's time zone"14 days before" is counted from the arrival date where the property is. Convert it to a clear date and time on the page and the voucher.
  • The supplier's policy winsWith API stock you cannot offer softer terms than the supplier gives you. With your own contracts you set the windows yourself.

Own stock and API stock

Your contracted properties and supplier APIs in one search

Most accommodation sellers do both: they load the places they contract themselves and add supplier APIs for everything else. The traveller should never notice where a stay came from.

Your own properties

  • Load properties, units and rate plans yourself in the admin
  • Give owners and hotels an extranet login to manage their calendar
  • Set prices, minimum stays, closed dates and cancellation windows
  • Allotments with release days and stop-sell
  • Or receive rates and availability from a channel manager

Supplier API stock

  • Large catalogues in destinations you could never contract
  • Live prices and availability at search time
  • Supplier boards, policies and fees on every rate
  • Switched on with your own supplier contract and credentials
  • Booking and cancellation sent straight to the supplier

What the guest gets

  • One results list with one property page per place
  • The same room from several sources shown once, at your price
  • Your markups by supplier, destination or channel, and B2B agent rates
  • One voucher format, whichever source confirmed it

Connecting a channel manager is covered on Channel manager integration. For rooms you hold under contract, see Booking inventory system.

Ready in PHPTRAVELS

Stays suppliers already connected

These accommodation suppliers are connected to the Stays module today. You sign with the supplier, enter your own credentials in the admin, test in their sandbox and go live. The list comes live from our integrations directory.

Need a supplier that is not listed, such as a regional rental network? Any accommodation API with documentation can be added, see Custom API integration. For hotel supplier types and content mapping, read the Hotels API page, and the two biggest bedbank guides: RateHawk API integration and Hotelbeds API integration.

Book a stay the way your guests will

Search, compare rates and book in the live demo, then tell us which properties and suppliers you plan to sell.

Try the live demoAsk about your suppliers

Building your own app or partner feed? The PHPTRAVELS REST API serves every connected stays source in one format, with webhooks for booking events. It comes with the Enterprise plan, see Pricing and the developer documentation. The wider picture is on Travel APIs.

FAQ

Stays API: questions developers and agencies ask

Talk to sales

A stays API is a set of web services that lets a booking site search accommodation, read prices and availability for given dates and guests, and create, read and cancel bookings. It covers hotels and every other kind of stay: apartments, vacation rentals, hostels and guesthouses.

The core calls are the same. A stays API also has to handle what non-hotel stays need: whole-unit bookings, minimum stays and changeover days, extra guest charges, cleaning fees, refundable deposits and check-in instructions sent before arrival.

Yes. In PHPTRAVELS the Stays module uses one model of property, unit, rate plan and availability for every type of accommodation, so hotels, apartments and holiday homes appear in the same search with their own rules.

Each night in the calendar can carry a minimum length of stay, usually tied to the arrival date. If a guest searches for fewer nights than the minimum, the unit is not returned. Closed-to-arrival and closed-to-departure flags work the same way for changeover days.

Yes. You can add properties, units, rate plans and calendars yourself, give owners an extranet login, or receive rates from a channel manager, and sell them next to supplier stock in one results list.

From the rate plan. Supplier stock carries the supplier's policy, and your own properties use the windows you set. The deadline is shown to the guest before payment and printed on the voucher.

No. You sign with each accommodation supplier and enter your own credentials in the admin. PHPTRAVELS provides the booking platform, the Stays module and the ready connectors.

Yes. On the Enterprise plan the PHPTRAVELS REST API exposes search and booking across every connected source in one format, with webhooks for booking events and full source code to extend it.

A PHPTRAVELS licence, your own domain and at least one source of stock: properties you contract yourself, a channel manager, or a supplier contract with an accommodation wholesaler. The live demo shows the full flow first.

Keep exploring

More from the platform