Pricing

Retrieve nightly prices, availability, and stay rules for your units.

💰 Pricing

Retrieve the rate calendar for your units: nightly price, availability, and minimum/maximum stay rules per date. Results are scoped to your permitted units and ordered by unit, then date.

• Method: GET

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

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

🔍 Query parameters

Parameter	Type	Description
from	string, optional	Start date (YYYY-MM-DD). Default: today
to	string, optional	End date (YYYY-MM-DD). Default: today + 365 days
unit	string, optional	Case-insensitive substring match on the unit's friendly_name
okupai_property_id	string, optional	Filter to a single unit by its UUID (same ID as in the Bookings endpoint)
changed_since	string, optional	ISO-8601 timestamp; return only rows changed after this moment — ideal for incremental syncs
sync_mode	string, optional	Use bootstrap for an initial or recovery full import
limit	integer, optional	Page size; default 1000, max 5000
offset	integer, optional	Items to skip; default 0

The maximum date window is 550 days per request. For longer horizons, split into multiple requests.

📦 Pricing item fields

One item per unit per date:

Field	Type	Description
okupai_property_id	string	UUID of the unit in OkupAI
friendly_name	string	Human-readable unit name
date	string	The night this row applies to (ISO date)
price	number	Nightly price for that date
available	boolean	Whether the night is open for sale
min_nights	number	Minimum nights for arrival on this date
max_nights	number	Maximum stay length; null when unlimited
changed_at	string	Last change timestamp; always included and used for incremental sync

The top-level response also includes "currency": "EUR" — all prices are returned in EUR.

🏨 Multi-room listings (parent & child units)

For multi-room setups (e.g. a building with several bookable rooms), pricing data lives on the parent object only:

• The parent object carries the pricing rows — it is the only one with availability values (>= 0)

• Child objects return no pricing data — they inherit price, availability, and stay rules from their parent

When querying by okupai_property_id, always use the parent's UUID to get the rate calendar. If a unit returns no pricing rows, it is most likely a child unit — resolve its parent and query that instead.

⚡ 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/pricing?from=2026-07-01&to=2026-07-31`, {
  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/pricing",
    headers={"X-API-Key": API_KEY},
    params={"from": "2026-07-01", "to": "2026-07-31"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

cURL

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

Example response (truncated):

{
  "total": 62,
  "limit": 1000,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "currency": "EUR",
  "items": [
    {
      "okupai_property_id": "123e4567-e89b-12d3-a456-426614174000",
      "friendly_name": "Main Apartment",
      "date": "2026-07-01",
      "price": 129.0,
      "available": true,
      "min_nights": 2,
      "max_nights": null,
      "changed_at": "2026-09-25T08:30:00"
    }
  ]
}

🔁 Incremental sync with changed_since

Poll only for changes instead of re-downloading the full calendar. Every item includes changed_at; pass the highest value from your completed sync as changed_since on the next run:

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  "https://api.okup.ai/data/pricing?changed_since=2026-07-01T00:00:00Z"

Process every page before advancing your saved timestamp. Use a small overlap and upsert by okupai_property_id plus date, so retries are safe. Collection responses also include an ETag; send it in If-None-Match for the exact same request URL and handle 304 Not Modified without parsing a body.

🔄 Required synchronization mode

Use changed_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 pricing lookup remains exempt when it includes okupai_property_id, from, and to and 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

• 400 Bad Request — invalid parameter (bad date format, invalid UUID, window over 550 days, to before from)

• 401 Unauthorized — missing X-API-Key header

• 403 Forbidden — invalid key or verification failed

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

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