Bookings

Retrieve bookings in a given date range.

📆 Bookings

Retrieve bookings in a given date range. Results are scoped to your permitted units and ordered by reservation_start (asc), then booking_date (asc).

• Method: GET

• Endpoint: https://api.okup.ai/data/bookings

• Auth: header X-API-Key: YOUR_API_KEY (required)

🔍 Query parameters

Parameter	Type	Description
from	string, optional	Inclusive start date filter on reservation_start (YYYY-MM-DD)
to	string, optional	Inclusive end date filter on reservation_start (YYYY-MM-DD)
unit	string, optional	Case-insensitive substring match on the unit's friendly_name
updated_since	string, optional	ISO-8601 timestamp; return only bookings inserted or changed after this moment
sync_mode	string, optional	Use bootstrap for an initial or recovery full import
limit	integer, optional	Page size; default 100, max 1000
offset	integer, optional	Items to skip; default 0

📦 Booking item fields

All fields may be null if unknown. Dates are ISO strings; monetary values are numbers (floats).

Field	Type	Description
internal_booking_id	string	Internal immutable identifier (UUID)
booking_id	string	Channel/source booking identifier
platform	string	Source platform
okupai_property_id	string	UUID of the unit in OkupAI — stable identifier, use it to join with the Pricing endpoint
friendly_name	string	Human-readable unit name
listing_id	string	Listing identifier on the platform
booking_date	string	When the booking was made (ISO date/datetime)
updated_at	string	Last insertion or update timestamp; use it for incremental synchronization
reservation_start	string	Check-in date (ISO date)
reservation_end	string	Check-out date (ISO date)
status	string	Current booking status
guest_name	string	Guest full name
email	string	Guest email
phone	string	Guest phone (as provided)
guest_origin	string	Raw channel/source label if present
guest_origin_gpt	string	Normalized/derived origin categorization
adults	number	Number of adult guests
children	number	Number of child guests
nights_price	number	Accommodation subtotal for nights
cleaning	number	Cleaning fee component
city_tax_platform	number	City/tourist tax as reported by platform
commission_host	number	Host commission/fee amount
currency	string	ISO currency code
payment_method	string	Payment method of the booking (e.g. Cash, Bank Transfer, Stripe, Platform, Paypal)
fx_rate_to_eur	number	FX rate applied to convert to EUR
fx_fixed_at	string	Timestamp when FX rate was fixed (ISO datetime)
fx_source	string	FX source/provider label

New fields: okupai_property_id and payment_method were added recently. okupai_property_id is the same UUID used by the Pricing endpoint, so you can join bookings and rates reliably — friendly_name can change, the UUID never does.

⚡ Basic example

JavaScript

// Server-side (Node 18+). Don't expose API keys in the browser.
const BASE_URL = 'https://api.okup.ai';
const API_KEY = process.env.OKUPAI_API_KEY;

const res = await fetch(`${BASE_URL}/data/bookings?from=2026-01-01&to=2026-01-31&limit=10`, {
  headers: { 'X-API-Key': API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const data = await res.json();
console.log(data);

Python

import os, requests

BASE_URL = "https://api.okup.ai"
API_KEY = os.environ["OKUPAI_API_KEY"]

r = requests.get(
    f"{BASE_URL}/data/bookings",
    headers={"X-API-Key": API_KEY},
    params={"from": "2026-01-01", "to": "2026-01-31", "limit": 10},
    timeout=30,
)
r.raise_for_status()
print(r.json())

cURL

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  "https://api.okup.ai/data/bookings?from=2026-01-01&to=2026-01-31&limit=10"

Example response (truncated):

{
  "total": 42,
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "next_offset": 10,
  "items": [
    {
      "internal_booking_id": "9a2a6b0f-3a3d-4c1e-8b8b-12f3f9a7f001",
      "booking_id": "123456789",
      "platform": "airbnb",
      "okupai_property_id": "123e4567-e89b-12d3-a456-426614174000",
      "friendly_name": "Main Apartment",
      "listing_id": "987654",
      "booking_date": "2026-01-02",
      "updated_at": "2026-09-25T08:30:00+00:00",
      "reservation_start": "2026-01-10",
      "reservation_end": "2026-01-12",
      "status": "OK",
      "guest_name": "Jane Doe",
      "email": "[e-mail]",
      "phone": "[phone]",
      "guest_origin": "app",
      "guest_origin_gpt": "direct",
      "adults": 2,
      "children": 0,
      "nights_price": 215.0,
      "cleaning": 35.0,
      "city_tax_platform": 4.8,
      "commission_host": 21.5,
      "currency": "EUR",
      "payment_method": "Platform",
      "fx_rate_to_eur": 1.0,
      "fx_fixed_at": "2026-01-02T08:30:00Z",
      "fx_source": "ECB"
    }
  ]
}

🔎 Filtering by unit name

Use unit to match friendly_name (case-insensitive substring):

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  "https://api.okup.ai/data/bookings?from=2026-01-01&to=2026-01-31&unit=Apartment"

🔁 Incremental sync with updated_since

After an initial import, poll only for inserted or changed bookings:

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  "https://api.okup.ai/data/bookings?updated_since=2026-09-25T08:00:00Z&limit=1000"

Process every page, upsert by internal_booking_id, and then store the highest updated_at value. Use that value as the next updated_since. For a safe retry boundary, subtract one second and make your upsert idempotent.

All successful collection responses include an ETag. Cache the ETag for the exact request URL and send it back:

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  -H 'If-None-Match: W/"PREVIOUS_ETAG"' \
  "https://api.okup.ai/data/bookings?updated_since=2026-09-25T08:00:00Z&limit=1000"

304 Not Modified means there is no response body to parse. See Pagination for the complete synchronization pattern.

🔄 Required synchronization mode

Use updated_since for recurring synchronization. Broad scans are deprecated and, for existing API keys, return 422 incremental_sync_required from 26 October 2026 at 00:00 UTC. You can perform an initial or recovery import with sync_mode=bootstrap; this opens a 30-minute pagination window and can start only once per API key every 24 hours.

A focused booking lookup with both from and to remains exempt when the date window is at most 90 days. See Pagination and incremental synchronization for the migration workflow, warning headers, bootstrap procedure, and error examples.

❌ Error codes

• 401 Unauthorized — missing X-API-Key header

• 403 Forbidden — invalid key or verification failed

• 422 Unprocessable Entity — recurring broad sync requires updated_since; see the pagination guide

• 429 Too Many Requests — wait for the Retry-After header before retrying