Partner API

Overview

The Partner API is a read-only REST API that lets integration partners query stays (bookings) for a property. Every API key belongs to a single property and only exposes the data categories the property administrator selected when creating it. All responses are JSON.

Authentication

Property administrators create API keys under Configuration → Integration API Keys in the host dashboard. Keys start with sa_ and the full secret is shown only once, at creation time — store it securely. Keys can be given an optional expiration date and can be revoked at any time.

Send the key on every request, either as a bearer token or in the X-Api-Key header:

Authorization: Bearer sa_your_api_key
# or
X-Api-Key: sa_your_api_key

Requests with a missing, invalid, expired, or revoked key receive 401 Unauthorized.

Base URL

https://stay.annwn.app/api/partner/v1

List stays

GET /stays

Returns the property's stays, newest bookings first. Cancelled stays are included (with "status": "cancelled") so you can reconcile changes; preview and merged-away duplicate stays are never returned.

Query parameters

Example request

curl -H "Authorization: Bearer sa_your_api_key" \
  "https://stay.annwn.app/api/partner/v1/stays?check_in_from=2026-09-01&check_in_to=2026-09-30&per_page=50"

Example response

{
  "data": [
    {
      "id": "5f0c1f6e-8a4b-4c2d-9e3f-1a2b3c4d5e6f",
      "status": "confirmed",
      "cancelled_at": null,
      "check_in": "2026-09-10",
      "check_out": "2026-09-12",
      "number_of_nights": 2,
      "guest_count": 2,
      "booked_at": "2026-07-01T12:34:56.000Z",
      "property": { "id": 12, "name": "Casa Oliva" },
      "created_at": "2026-07-01T12:34:56.000Z",
      "updated_at": "2026-07-01T12:34:56.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}

Get a stay

GET /stays/:id

Fetches a single stay by its id (a UUID, as returned by the list endpoint). Returns 404 when the stay does not exist or belongs to a different property. The response wraps the stay object in a data key.

The stay object

The core fields below are always present. The four additional sections appear only if the API key was granted the matching data-access category by the property administrator.

Core fields (always present)

Guest details scope: guest details

Adds guest_notes, special_requests, and a guests array where each guest has name, email, phone, country_code, city, checked_in, checked_out, and is_contact (true for the booking contact).

Financials scope: financials

Adds a financials object. All amounts are integers in the smallest currency unit (cents).

"financials": {
  "currency": "USD",
  "price_total_cents": 48000,
  "payments_total_cents": 20000,
  "pending_balance_cents": 28000,
  "deposit_amount_cents": 5000,
  "refundable_total_cents": 43000,
  "ota_commission_cents": 7200,
  "payment_state": "partial"
}

payment_state is paid, partial, unpaid, or null when the stay has no charges yet. deposit_amount_cents is null when no deposit is configured.

Room assignments scope: room assignments

Adds a units array with one entry per booked room: unit_type (room category name), unit (assigned room name, null while unassigned), and the room's own check_in / check_out dates.

Booking source scope: booking source

Adds a channel object: name (e.g. booking, airbnb, direct), display_name, remote_id (the OTA reservation ID, null for direct bookings), and channel_email.

Errors

Errors share one JSON shape:

{ "error": { "code": "invalid_api_key", "message": "Missing, invalid, revoked, or expired API key" } }

Rate limits

Requests are limited to 120 per minute per API key. Exceeding the limit returns 429; wait and retry.