Wire conventions — the shapes every QC response follows

One page for the rules every QC endpoint applies to its response. Read this once, then you know how to interpret every list, every name, every money value, and every filter across all endpoints.

Envelope

Every response has this outer shape:

{
  "status": "ok",           // or "error"
  "message": "ok",          // or an error translation key
  "data": { … }
}

• message is always a translation key, never a rendered string. Match on it, don't parse it — see the error dictionary for the full list.
• status is ok or error. HTTP status also disambiguates, but the field lets a client route based on the JSON alone.
• data is the payload. Its shape depends on the endpoint:

Single-item read/write. data IS the resource object, flat:

{"status": "ok", "message": "ok", "data": {"external_property_id": "…", "name": "…", …}}

List read. data holds a plural-keyed array + a meta block:

{
  "status": "ok",
  "message": "ok",
  "data": {
    "bookings": [ … ],
    "meta": {"total": 4231, "page": 1, "per_page": 50, "last_page": 85}
  }
}

The plural key names the resource (bookings, properties, room_types, rate_plans, webhook_deliveries, …). Never data.data.

Identifiers

Every resource that can be addressed by an external id emits it under a canonical external_<resource>_id key AND a back-compat id alias with the same value:

{"external_property_id": "059020b9-…", "id": "059020b9-…", …}

• external_*_id is the recommended read. Path parameters use the same name (/properties/{external_property_id}/…), so the wire round-trips exactly.
• id is preserved for early adopters — it will not be removed, but new consumers should read external_*_id.

Internal Quendoo primary keys (property_id, room_id, rate_id, …) are NEVER exposed on the wire. The partner side never sees them.

Names and translations

Every named entity (property, room type, rate plan, extra, promotion, cancellation policy, payment policy, special offer) emits:

• name — the hotelier-set label in Quendoo's canonical language (en-GB). Never null for entities that have a name; nullable ONLY when the underlying legacy row cannot be resolved (rare — enrolment refuses to seed a QC map without one).
• name_tr — the full translation map, keyed by IETF locale tag: {"en-GB": "Superior Sea View", "bg-BG": "Супер изглед…", "ru-RU": "Улучшенный …"}. Empty object {} when the entity has no translations. Some entities (payment_policy, promotion) are stored without translation columns on the legacy side; they emit a one-locale projection {"en-GB": "<name>"} so callers can loop over _tr uniformly across every named entity.

Some entities carry additional translated fields (description_tr, title_tr, text_tr) — see the resource schemas in the reference.

Money

Every monetary field is {amount, currency}, never a bare float:

{"total_price": {"amount": 234.5, "currency": "EUR"}}

• amount is a float in the currency's native unit (2 decimal places for every currency we support).
• currency is an ISO 4217 alpha-3 code.

Booking rows carry a top-level currency field as a convenience for dashboards that render one currency badge per booking, but every per-line-item price ALSO carries its own currency in the wrapped shape. A partner storing lines in their own DB doesn't have to reach outside the row to know what a number means.

Pagination

Every list endpoint that can grow past ~100 rows takes ?page=N&limit=M and emits a meta block:

"meta": {"total": 4231, "page": 1, "per_page": 50, "last_page": 85}

• total reflects the row count under the ACTIVE filters (not the unfiltered table).
• last_page is ceil(total / per_page); always at least 1 even for an empty result, so a UI can render "page 1 of 1" without a null check.
• per_page echoes back the effective limit after clamping.
• limit is clamped to a per-endpoint MAX_LIMIT (typically 100–200); a value over the cap is silently reduced.

Some endpoints use CURSOR pagination instead — the booking revisions feed is the canonical example (?since=<revision_id> returns the next batch after a known point, with next_cursor in the response). Cursor endpoints do NOT carry the meta block; they carry next_cursor and has_more. Each concept page names which pattern its endpoint uses.

Filters

Filter conventions apply across every endpoint that accepts them:

• Malformed values are DROPPED, not 422. A ?checkin_from= bogus request does not narrow — the filter is silently ignored. This is a deliberate Channex-parity choice: partner code that ships a bad filter should still surface the same rows, not fail loudly.
• Date filters accept two shapes: YYYY-MM-DD (day precision) or YYYY-MM-DD HH:MM:SS (second precision). Others are dropped.
• Enum filters whitelist to prevent injection. A value not in the enum is dropped, not 422.
• String filters are trimmed and length-capped at endpoint-appropriate limits (typically 32 for identifiers, 100 for guest fields).

Every list endpoint's concept page names its supported filters in a table with types + notes.

Statuses & lifecycles

Two orthogonal status axes on Booking:

• processing_state — QC ingest-pipeline lifecycle (staged → promoted | rejected | duplicate). Partner- useful for "did QC accept my write and move it on to the projector?".
• booking_status — business state (created | confirmed | cancelled | no_show), derived from terminal timestamps. This is what integrators want to render in a UI. Order matters — a cancelled-then- marked-no-show booking reads as cancelled because the terminal action happened first when the booking was still active. status is a deprecated alias to processing_state.

Errors

Errors share the envelope with status: "error":

{"status": "error", "message": "errors.qc.unknown_room_type"}

• message is a stable translation key. Match on it, don't parse it.
• Validation errors add an errors map: {"scopes.0": [{"key": "validation.in", "params": {…}}]}.
• HTTP status distinguishes categories: 401 (missing/invalid auth), 403 (auth valid but forbidden), 404 (unknown resource OR scope), 409 (idempotency conflict), 422 (validation), 429 (rate limit), 502 (upstream failure).

PII

Guest-level fields (guest_name, first_name, last_name, email, phone) are MASKED on QC responses even when the underlying dashboard would show them unmasked to the hotelier. The reasoning: QC tokens are held by partner PMSes, not the account holder. See Auth concepts for the full masking rules.

Idempotency

Every write endpoint honours Idempotency-Key: <uuid> on the request. See Idempotency for the contract.

Rate limits

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. See Rate limits.