> For the complete documentation index, see [llms.txt](https://docs.okup.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.okup.ai/okupai-api/bookings.md).

# 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`    |
| `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)                                                |
| `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                                                                     |

{% hint style="info" %}
**New fields:** `okupai_property_id` and `payment_method` were added recently. `okupai_property_id` is the same UUID used by the [Pricing endpoint](/okupai-api/pricing.md), so you can join bookings and rates reliably — `friendly_name` can change, the UUID never does.
{% endhint %}

### ⚡ Basic example

{% tabs %}
{% tab title="JavaScript" %}

```js
// 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);
```

{% endtab %}

{% tab title="Python" %}

```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())
```

{% endtab %}

{% tab title="cURL" %}

```bash
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"
```

{% endtab %}
{% endtabs %}

Example response (truncated):

```json
{
  "total": 42,
  "limit": 10,
  "offset": 0,
  "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",
      "reservation_start": "2026-01-10",
      "reservation_end": "2026-01-12",
      "status": "OK",
      "guest_name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+1234567890",
      "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):

```bash
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"
```

### ❌ Error codes

* **401 Unauthorized** — missing `X-API-Key` header
* **403 Forbidden** — invalid key or verification failed