Overview

The Booking Engine API allows external platforms to:

Search available properties
Retrieve pricing and calendar data
Create bookings

Key components

Base URL: https://booking-api.guesty.com/v1
Format: JSON over HTTPS
Authentication: OAuth2 access token (included in header)

Prerequisites

A Guesty account with Booking Engine enabled (see Step 1 in the next section below)
An API key (provided in the Guesty dashboard - see Step 2 in the next section below)
Familiarity with HTTP requests and JSON responses
A tool for testing requests (Postman, curl, or browser)

Activating the Booking Engine

Step 1: Create a booking Engine API instance

To begin using the Booking Engine API, you need to create an API instance and retrieve your credentials (Client ID and Client Secret). Take care to ensure that you select the booking option (Only request to book, Only instant booking, or Both request to book and instant book) that aligns with your intended booking flow. For example, if you select Only Inquiries, you will only be able to create booking requests ("status": "reserved").

📖 For detailed instructions, refer to this Guesty Help Center article.

Step 2: Get your access token

Note: Guesty enforces the following access token limitations:

Tokens expire after 24 hours.
Each application requires its own token.
You can create up to 5 applications per Guesty account.
The token can be renewed up to 3 times within a 24-hour period.

To avoid interruptions, store and reuse tokens until they expire.

Managing your token for uninterrupted access

To maintain uninterrupted access and avoid exceeding token issuance limits, consider the following token management strategy:

Store the token securely using environment-specific strategies:

For backend services, use in-memory caching or encrypted secure files.
If writing to disk, encrypt the file using a secure method and restrict file permissions.
Avoid committing tokens to source control.
Never store tokens in frontend or client-side code.

Track its expiration time using the expires_in field from the token response (usually 86400 seconds).
Reuse the stored token for all API requests until it is close to expiring.
Automatically request a new token only when the current one is about to expire (e.g., within the last 5 minutes).
Avoid requesting a new token on every API call to prevent hitting the renewal limit of 3 tokens per 24 hours per application.

To interact with the Booking Engine API, you'll need to authenticate using OAuth2 to obtain an access token. Here's how to request a token using your client credentials:

Request

curl --location --request POST 'https://booking.guesty.com/oauth2/token' \
--header 'accept: application/json' \
--header 'cache-control: no-cache,no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=booking_engine:api' \
--data-urlencode 'client_secret={application client SECRET}' \
--data-urlencode 'client_id={application client ID}'

const axios = require('axios');

async function getAccessToken() {
  const params = new URLSearchParams();
  params.append('grant_type', 'client_credentials');
  params.append('scope', 'booking_engine:api');
  params.append('client_id', 'YOUR_CLIENT_ID');
  params.append('client_secret', 'YOUR_CLIENT_SECRET');

  const response = await axios.post('https://booking.guesty.com/oauth2/token', params, {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  });

  console.log(response.data.access_token);
}

import requests

payload = {
    'grant_type': 'client_credentials',
    'scope': 'booking_engine:api',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET'
}

response = requests.post('https://booking.guesty.com/oauth2/token', data=payload)
print(response.json()['access_token'])

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://booking.guesty.com/oauth2/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'accept: application/json',
    'cache-control: no-cache,no-cache',
    'content-type: application/x-www-form-urlencoded'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'grant_type' => 'client_credentials',
    'scope' => 'booking_engine:api',
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET'
]));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['access_token'];

Response

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 86400
}

Use the access_token in the Authorization header of all subsequent API requests:

--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Step 3: Test your access token with a listings search

Request:

curl --location GET 'https://booking-api.guesty.com/v1/search
accept: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Optional query parameters include:

checkIn, checkOut (YYYY-MM-DD)
guests, adults, children
location

Example:

curl --location --request GET 'https://booking-api.guesty.com/v1/search?checkIn=2025-07-01&checkOut=2025-07-05&adults=2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Step 4: Activate the booking flow

Before using the Booking Engine (BE) API reservation endpoints, ensure it is properly activated by following these steps:

Activate the_manual_ source: Create a direct booking from your Guesty dashboard to activate the manual booking source in your account.
Activate the Booking Engine API source: Create your first reservation using the BE API Reservation quote endpoints. This step is essential to initialize the Booking Engine API source, which enables it as an automation option for additional fees, taxes, payment automations, and automated messages.

If you encounter any issues, feel free to contact us for assistance.

Rate limits

Guesty enforces the following rate limits on the Booking Engine API:

5 requests per second
275 requests per minute
16,500 requests per hour

Guesty uses a gradual refill method to restore your request capacity over time, rather than resetting it all at once. This means you should avoid burst traffic and allow time for capacity to replenish between requests.

Recommendations

Distribute traffic evenly across time to avoid bursts.
Implement exponential backoff with jitter and a maximum cap when you receive HTTP 429 (Too Many Requests) responses.
Monitor API response headers for rate limit usage if exposed.

Best practices

Always include the Authorization header
Validate inputs before sending requests
Handle 4xx and 5xx responses gracefully
Display accurate availability and pricing by using real-time API data

⚠️
Note:
Guesty recommends using the Reservation Quote Flow for all booking operations. The older Reservations V1 endpoint is being deprecated and should not be used in new implementations.

Resources

Troubleshooting authentication issues

If you encounter authentication issues with the Booking Engine API, here are some common causes and tips:

Common issues

Invalid client ID or secret

Double-check credentials for typos and correct copying.

Incorrect headers

Ensure you include Content-Type: application/x-www-form-urlencoded and use accept: application/json.

Token expiration

Tokens expire after 24 hours. Cache and reuse the token as described.

Token renewal limit

Tokens can only be renewed 3 times in 24 hours. Avoid excessive regeneration.

Missing authorization

Include the header Authorization: Bearer YOUR_ACCESS_TOKEN in all requests.

Getting help

If issues persist, contact Guesty support.

Next steps

Explore the Booking Engine API Documentation
Review available filters and sort options for search
Read through the Booking Engine API Guides for implementation tips
Implement error-handling and availability fallback logic