Conventions

Dates, money, pagination, idempotency, rate limits, errors and versioning.

Dates and money

Dates are YYYY-MM-DD. A stay is [check-in, check-out); the departure day is excluded. A calendar day is one night.
Amounts are integers in minor units (totalMinor: 105000 = 1,050.00 EUR) with an ISO 4217 currency. A property's prices stay in the owner's currency; we do not convert.
The time zone belongs to the property (timezone); day boundaries follow the property's local day.

Language

Pass locale=tr|en for names and catalogue fields. Catalogue keys (like pool.private) are language-neutral and never renamed.

Pagination

The property list uses a cursor: pass the nextCursor of an answer as cursor in the next request; null means the last page. The event log moves on with after (next_after).

Idempotency

Add an Idempotency-Key header (a UUID is fine) to hold and reservation requests. If the network drops and you repeat the request with the same key, no second record is made; you get the first answer.

Rate limits

A live key may make 600 requests a minute, a test key 120. Every answer carries the state in headers:

http

RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 41

Beyond the limit you get 429 rate_limited; try again after RateLimit-Reset seconds. Prefer webhooks to polling.

Errors

Errors are RFC 9457 application/problem+json. Your program should branch on code; detail is for humans and may change.

json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "dates_unavailable",
  "detail": "dates_unavailable"
}

All error codes are listed on the Error codes page.

Versioning

Addresses start with /v1. Backwards-compatible additions (a new field, endpoint or event type) do not change the version; your receivers must ignore fields and event types they do not know. A breaking change ships as a new major version and is announced in the Changelog. api_version in webhook payloads shows the release date.