Beds24 API V2: access, endpoints, limits and the pitfalls we hit

API V1 or V2, and where is the API key?

API V1 is deprecated and “will not be developed further” (Beds24 wiki). Its JSON functions used an API key and a property key that you set yourself: that is what an app or an old tutorial means by a “Beds24 API key”.

API V2 has no key. Access comes with every Beds24 account: you create an invite code under MARKETPLACE > API in your settings, and the app exchanges it for tokens. Beds24 recommends V2 “for all new integrations” (Beds24 API V2 documentation); if the API menu is missing, its support can enable it.

Asked for your API key? Send a V2 invite code with only the permissions the app needs, never your Beds24 password.

How authentication works: invite code, refresh token, token

1. You create an invite code and pick its scopes. It is valid 24 hours and works once.
2. The app exchanges it with GET /authentication/setup (header code) and receives a token and a refreshToken.
3. Each call sends the token in a token header. A token lasts 24 hours: reuse it, since requesting a new one costs credits.
4. When it expires, GET /authentication/token with the refreshToken header returns a fresh one.

# Exchange the invite code (once, within 24 hours)
curl -H "code: <INVITE_CODE>" https://api.beds24.com/v2/authentication/setup
# → { "token": "<TOKEN>", "expiresIn": 86400, "refreshToken": "<REFRESH_TOKEN>" }

# Call the API
curl -H "token: <TOKEN>" https://api.beds24.com/v2/properties

# Renew the token
curl -H "refreshToken: <REFRESH_TOKEN>" https://api.beds24.com/v2/authentication/token

The refresh token dies after 30 days without use: store it encrypted on your server and renew the token daily. Read-only jobs can use a long life token instead, which expires after 90 days unused. Vendors with many Beds24 customers can apply to the marketplace partner programme: properties then activate their app with a click, without an invite code.

Scopes: what an invite code allows

Scopes are fixed when the invite code is created; to change them, create a new code. Each scope takes a method: read:bookings, write:bookings or all:bookings.

The form also covers linked properties (off by default) and an IP whitelist. Grant only what the app needs: our booking page asks for bookings, inventory and properties, read and write.

Main endpoints and the official documentation

Everything lives under https://api.beds24.com/v2. Endpoints marked alpha are usable but still changing; beta ones are mostly finished.

curl -H "token: <TOKEN>" \
  "https://api.beds24.com/v2/inventory/rooms/offers?propertyId=<PROPERTY_ID>&arrival=2026-11-12&departure=2026-11-14&numAdults=2"

The interactive Swagger documentation shows an example per endpoint and lets you try calls with your token; help pages and changelog are on the Beds24 wiki.

Pitfalls we hit while integrating

We built our Beds24 booking engine on this API. These traps cost us the most time; each was confirmed against the live API:

• numAdults, plural, in the offers query. numAdult returns a misleading 2002 Occupancy not defined. Bookings, though, use numAdult and numChild.
• Offer prices exclude the tourist tax: add city tax yourself if guests must see the full amount.
• Beds24 does not price API bookings. Without invoice items a booking arrives at 0, and the total is not computed from the lines: send price and the items.
• Send checkAvailability: true in the actions, so Beds24 refuses a room taken a second ago.
• Tag bookings with apiReference (up to 100 characters): Beds24 rewrites referer to “API”, and GET /bookings?apiReference=… finds yours.
• There is no sandbox, and staging does not fully mirror production: test on a room you can spare.
• Credit headers differ from the OpenAPI file: read x-five-min-limit-remaining, x-five-min-limit-resets-in and x-request-cost.

POST https://api.beds24.com/v2/bookings
token: <TOKEN>

[{
  "roomId": <ROOM_ID>,
  "arrival": "2026-11-12",
  "departure": "2026-11-14",
  "numAdult": 2,
  "firstName": "<FIRST_NAME>",
  "lastName": "<LAST_NAME>",
  "status": "confirmed",
  "price": 286.00,
  "apiReference": "<YOUR_APP>:<YOUR_REFERENCE>",
  "invoiceItems": [
    { "type": "charge", "description": "Double room, 2 nights", "qty": 1, "amount": 280.00 },
    { "type": "charge", "description": "City tax", "qty": 1, "amount": 6.00 }
  ],
  "actions": { "checkAvailability": true }
}]

A room type with no offer is what shows as “No price found” on the Beds24 booking page: see how to fix “No price found”.

Limits, credits and API pricing

Each account gets 100 credits per 5 minutes, shared by all its tokens, properties and connected apps. Complex requests cost more; ours typically cost one to two credits. Over the limit, calls fail (for example with 429) until the window resets.

API access itself comes with the account. Beds24 charges €10 a month per account or sub-account for 200 credits per 5 minutes, and support can go higher. Before paying, reuse tokens, batch writes (about 1 MB or 10,000 items per POST), request several IDs per GET and use webhooks rather than polling.

Webhooks instead of polling

Beds24 sends three kinds of webhooks (Beds24 wiki):

• Booking webhooks, set per property in (SETTINGS) PROPERTIES > ACCESS: new bookings and significant changes such as new dates or a cancellation, not every edit of guest details. Version 2 posts JSON.
• Inventory webhooks, set in (SETTINGS) MARKETPLACE > WEBHOOKS, when availability or prices change.
• Auto action webhooks, fired by your Beds24 auto actions.

Expect about a minute of delay. Bookings created through the API only trigger webhooks with the allowWebhooks action. Each property has one booking webhook URL: if another app uses it, do not overwrite it; poll GET /bookings with modifiedFrom, as we do.

Would an existing app do the job? See Beds24 integrations and Beds24 dynamic pricing.

Frequently asked questions