# ZimmerStack Connect API: the full reference > Everything on https://docs.zimmerstack.com in one file, generated 2026-11-17 from the live API contract (ZimmerStack Connect API v1). Routes, fields, samples, limits and codes are the server's own. If you are an AI coding agent, the rules at https://docs.zimmerstack.com/agents.md come first. Two kinds of key: a HOTEL KEY for one property, and a software vendor's COMPANY KEY for every hotel it may act on, which names the hotel on each request in the X-ZS-Property header (GET /properties lists them). Two integrations, one key format. CHANNEL MANAGER (scopes ari:*, catalog:write, channel-bookings:read): your PMS owns the room types and rate plans, pushes availability, rates and restrictions; ZimmerStack fans them out to every connected OTA, and OTA bookings reach you through the outbound webhooks (GET /api/v1/public/webhooks/contract) or GET /channel-bookings. When the hotel also sells on its own website through the ZimmerStack booking engine, those bookings reach you the same way under their own names: the direct.booking.* webhooks and GET /direct-bookings (scope direct-bookings:read). PMS (scopes bookings:*): your OWN booking engine hands the reservation your website sold to the ZimmerStack PMS; inventory and the channels update exactly as for a front-desk booking. A channel-manager-only tenant has no booking endpoints on purpose: a walk-in in its PMS becomes an absolute availability count here. ## Basics - Base URL: `https://api.zimmerstack.com/api/v1/connect-api/v1` - Auth: Authorization: Bearer zsk_live_… (zsk_test_… on a sandbox). zsk_live_ (or zsk_test_ on a sandbox) + 43 base64url characters; shown once at creation; a hotel key = one property, a company key = a software vendor's hotels. - Never send the key in: query string, x-api-key, user-api-key. - Envelope: every answer is `{ "statuscode", "message", "data" }`; a refusal carries a stable `data.code`. - Dates: YYYY-MM-DD, calendar dates in the property's timezone (GET /property); a stay occupies [checkIn, checkOut) — the checkout day is not a night. - Money: rates are SENT in major units with the property's currency and RETURNED in minor units (rateMinor); stored as whole major units. - Writes: absolute values, last write wins within a request, unchanged cells are dropped before anything is written. - Idempotency: send `x-idempotency-key` on every write; an answer is replayed for 7 days. A 429 or a 5xx is never stored, so the retry runs. ## Keys and scopes Two kinds of key, one API. A HOTEL KEY is bound to one property: the property is implicit and needs no header (an X-ZS-Property naming another property is 404 PROPERTY_NOT_FOUND). A COMPANY KEY belongs to a software vendor and reaches every hotel the vendor may act on: name the hotel on every request with the X-ZS-Property header, its id from GET /properties. GET /properties says which kind you hold (keyKind). Routes, bodies and answers are the same for both. A key holds the scopes the owner granted at creation (editable later without rotating). Every route names the one scope it needs; a key without it is 403 SCOPE_MISSING. bookings:payments needs bookings:write. GET /property echoes this key's scopes. | Scope | Lets the key | |---|---| | `ari:read` | Read availability, rates, restrictions and sync state from our record | | `ari:write` | Set availability, rates and restrictions (pushed to every connected channel) | | `catalog:write` | Create and change room types and rate plans (created on the channel manager and mirrored there) | | `channel-modifiers:write` | Set a channel's price modifier: one change moves every price sent to that channel from then on | | `channel-bookings:read` | Read the OTA bookings the channel manager delivered to this property, in the webhook's shape | | `direct-bookings:read` | Read the bookings guests made on the hotel's own website (our booking engine), in the webhook's shape | | `bookings:read` | Read bookings this key created | | `bookings:write` | Create and cancel bookings in the PMS (inventory updates and reaches the channels) | | `bookings:payments` | Record a payment on a booking it creates (needs bookings:write) | Address allowlist: Optional per key: up to 20 IPv4/IPv6 addresses or CIDR ranges. Set it to your servers' egress addresses: a request from anywhere else is 403 IP_NOT_ALLOWED, counts against the address's authentication budget, and is shown to the owner. Company keys (software vendors): - Header: `X-ZS-Property: ` - Without it: 400 PROPERTY_REQUIRED (GET /properties is the one route that needs no header) - A hotel it may not act on: 404 PROPERTY_NOT_FOUND for a property the key may not act on, whether or not it exists - Reach: A live company key reaches the hotels the vendor enrolled and any hotel whose owner allowed the vendor (Integrations → Software vendors, by the vendor code); the owner can revoke that any time and the key stops reaching the hotel at once. A test company key reaches the vendor's own sandbox only. - Scopes: Channel-manager scopes only: ari:read, ari:write, catalog:write, channel-modifiers:write, channel-bookings:read, direct-bookings:read. A hotel's PMS bookings (bookings:*) need that hotel's own key. - Budgets: Each hotel keeps its own per-key and per-property budgets; the company key also has one budget across all its hotels (x-zimmerstack.limits.companyRequestsPerMinute). What the integrator must do: - **Keep the key on a server.** Never in a browser, a mobile app, a repository or a chat. Load it from your secret store; one key per environment. - **Set the allowlist.** Give the owner your servers' public egress addresses. If they change, the owner edits the key; no rotation needed. - **Grant the least.** A booking engine needs bookings:write (and bookings:read to reconcile); add bookings:payments only if your site collects money. A PMS needs the ari pair. - **Rotate on any doubt.** A rotated key keeps the old one answering for 24 hours; swapping costs nothing. Revoke on a confirmed leak. - **Use externalReference.** Your own reservation id makes every retry safe: the same value returns the same booking. Send it always. - **Verify webhooks.** Check the signature with a constant-time compare, refuse stale timestamps, and treat deliveries as at-least-once. - **Watch the owner's screens.** Admin → Developers shows every key's last use, refused addresses and every API booking. Ask the owner to look if anything seems off. ## Routes | Route | What it does | Scope | |---|---|---| | `GET /availability` | Availability as our record holds it | `ari:read` | | `GET /batches/{batchId}` | One accepted write and whether it has landed | `ari:read` | | `GET /catalog` | Room types and rate plans with the numeric ids every write uses | any key | | `GET /channel-bookings` | The OTA bookings the channel manager delivered, in the webhook's shape | `channel-bookings:read` | | `GET /channel-bookings/{bookingId}` | One channel booking, the webhook's shape | `channel-bookings:read` | | `GET /channels` | The connected channels and their open issues, from our record | `ari:read` | | `GET /direct-bookings` | The bookings guests made on the hotel's own website, in the webhook's shape | `direct-bookings:read` | | `GET /direct-bookings/{bookingId}` | One website booking, the webhook's shape | `direct-bookings:read` | | `GET /properties` | The properties this key may act on | any key | | `GET /property` | The property this key is for | any key | | `GET /rates` | Rates as our record holds them (minor units) | `ari:read` | | `GET /restrictions` | Restrictions as our record holds them | `ari:read` | | `GET /sandbox/bookings` | Simulated OTA bookings on the sandbox, newest first | `ari:read` | | `GET /sync` | Has what you sent reached the channels? | `ari:read` | | `PUT /availability` | Set absolute availability | `ari:write` | | `PUT /catalog/rate-plans` | Create or change rate plans by your own ref | `catalog:write` | | `DELETE /catalog/rate-plans/{ratePlanId}` | Delete a rate plan: the channel manager's copy first, then ours | `catalog:write` | | `PUT /catalog/room-types` | Create or change room types by your own ref | `catalog:write` | | `DELETE /catalog/room-types/{roomTypeId}` | Delete a room type: the channel manager's copy first, then ours; its plans go with it | `catalog:write` | | `PUT /channels/{channelId}/modifier` | Set one channel's price modifier | `channel-modifiers:write` | | `PUT /rates` | Set nightly sell prices | `ari:write` | | `POST /rates/resend` | Send the property's prices to the channels again | `ari:write` | | `PUT /restrictions` | Set stay restrictions | `ari:write` | | `POST /sandbox/bookings` | Simulate an OTA booking on the sandbox: the booking, the inventory, the real webhook | `ari:write` | | `POST /sandbox/bookings/{bookingId}/cancel` | The channel cancels a simulated booking: availability back, the real cancelled webhook | `ari:write` | | `POST /sandbox/bookings/{bookingId}/modify` | The channel sends a modified revision: new dates, length, rooms or guest; the real modified webhook | `ari:write` | | `GET /bookings` | Bookings the API created on this property, newest first | `bookings:read` | | `GET /bookings/{bookingId}` | One booking the API created | `bookings:read` | | `POST /bookings` | Create a booking in the PMS from your own booking engine | `bookings:write` | | `POST /bookings/{bookingId}/cancel` | Cancel a booking the API created; its nights re-open on the channels | `bookings:write` | ### GET /availability Availability as our record holds it. Scope `ari:read`. Served from our record, never from the channel manager. Query: - `from`: Default: today in the property's timezone - `to`: Default: from + 30 days; at most 500 days after from Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `from` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `to` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `cells` | array of objects | yes | | | `cells[].roomTypeId` | integer | yes | | | `cells[].date` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `cells[].available` | integer | yes | | ### GET /batches/{batchId} One accepted write and whether it has landed. Scope `ari:read`. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `batchId` | string (uuid) | yes | | | `resource` | "availability" · "rates" · "restrictions" | yes | | | `createdAt` | string | yes | | | `requestedCells` | integer | yes | | | `acceptedCells` | integer | yes | | | `noopCells` | integer | yes | | | `rejected` | array of objects | yes | | | `rejected[].cells` | integer | yes | | | `rejected[].error` | string | yes | | | `status` | "landed" · "pending" · "failed" | yes | | | `pendingCells` | integer | yes | | | `parkedCells` | integer | yes | Cells of this batch the channel manager refused: held, not re-sent (§6.6). More than 0 reads failed | | `lastError` | string or null | yes | | Sample answer (`data`): ```json { "batchId": "7f1d2c4e-5a6b-4c8d-9e0f-112233445566", "resource": "rates", "createdAt": "2026-10-12T09:14:03.201Z", "requestedCells": 151, "acceptedCells": 43, "noopCells": 108, "rejected": [], "status": "pending", "pendingCells": 12, "parkedCells": 0, "lastError": null } ``` ### GET /catalog Room types and rate plans with the numeric ids every write uses. Any key. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `currency` | string | yes | ISO 4217; the property's, and the one every rate and booking is sent in | | `roomTypes` | array of objects | yes | Every room type on the property, stable ids, in the order they were created | | `roomTypes[].id` | integer | yes | The number every availability write and every booking room names as roomTypeId | | `roomTypes[].ref` | string or null | yes | Your own id for it, when your system wrote it through PUT /catalog/room-types; null otherwise | | `roomTypes[].name` | string | yes | As the owner named it in ZimmerStack | | `roomTypes[].maxAdults` | integer or null | yes | Most adults one room takes; null = not set | | `roomTypes[].maxChildren` | integer or null | yes | Most children one room takes; null = not set | | `roomTypes[].roomKind` | string | yes | "room" unless the owner chose another kind of unit | | `roomTypes[].sync` | string (7 values) | yes | IN_SYNC the channel manager has it · PENDING / SENDING on its way · FAILED stopped retrying (the owner's screen offers Retry) · DRIFTED someone changed it inside the channel manager · NOT_LINKED saved here, never added there · DISABLED the property is not connected | | `ratePlans` | array of objects | yes | Every rate plan, each under one room type | | `ratePlans[].id` | integer | yes | The number rate and restriction writes name as ratePlanId; optional on a booking room | | `ratePlans[].ref` | string or null | yes | Your own id for it, when your system wrote it through PUT /catalog/rate-plans; null otherwise | | `ratePlans[].roomTypeId` | integer | yes | The room type this plan sells; a booking may only pair the two | | `ratePlans[].name` | string | yes | As the owner named it | | `ratePlans[].mealPlan` | "EP" · "CP" · "MAP" · "AP" or any or null | yes | EP room only · CP breakfast · MAP half board · AP full board; null = not set | | `ratePlans[].occupancy` | integer or null | yes | The occupancy this plan is priced for; null = any | | `ratePlans[].currency` | string | yes | | | `ratePlans[].refundable` | boolean | yes | false = a non-refundable plan | | `ratePlans[].sync` | string (7 values) | yes | IN_SYNC the channel manager has it · PENDING / SENDING on its way · FAILED stopped retrying (the owner's screen offers Retry) · DRIFTED someone changed it inside the channel manager · NOT_LINKED saved here, never added there · DISABLED the property is not connected | Sample answer (`data`): ```json { "currency": "INR", "roomTypes": [ { "id": 412, "ref": "rt-deluxe", "name": "Deluxe Garden Room", "maxAdults": 2, "maxChildren": 1, "roomKind": "room", "sync": "IN_SYNC" }, { "id": 413, "ref": null, "name": "Family Suite", "maxAdults": 4, "maxChildren": 2, "roomKind": "room", "sync": "IN_SYNC" } ], "ratePlans": [ { "id": 901, "ref": "rp-bb", "roomTypeId": 412, "name": "Bed and breakfast", "mealPlan": "CP", "occupancy": 2, "currency": "INR", "refundable": true, "sync": "IN_SYNC" }, { "id": 902, "ref": null, "roomTypeId": 413, "name": "Room only, non-refundable", "mealPlan": "EP", "occupancy": 4, "currency": "INR", "refundable": false, "sync": "PENDING" } ] } ``` ### GET /channel-bookings The OTA bookings the channel manager delivered, in the webhook's shape. Scope `channel-bookings:read`. Scope channel-bookings:read. Oldest change first; since (default the last 7 days) is on the booking's last change so cancellations and modifications are listed again; while more is true, ask again with cursor = nextCursor, which resumes exactly after the last item even when many bookings changed in the same instant. Query: - `since`: Changed on or after this instant (ISO 8601); default: the last 7 days - `status`: Only confirmed or only cancelled; default both - `limit`: Default 50 - `cursor`: The previous page's nextCursor; takes precedence over since. One this API did not issue is 400 VALIDATION Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `since` | string | yes | The instant the list starts at, echoed | | `items` | array of objects | yes | Oldest change first — exactly the booking object the webhooks carry | | `items[].id` | integer | yes | | | `items[].reference` | string | yes | | | `items[].status` | "CONFIRMED" · "CANCELLED" | yes | | | `items[].stayStatus` | string | yes | | | `items[].channel` | object | yes | | | `items[].channel.otaName` | string | yes | | | `items[].channel.otaReservationCode` | string | yes | | | `items[].channel.source` | string | yes | | | `items[].channel.sourceGroup` | string | yes | | | `items[].stay` | object | yes | | | `items[].stay.checkIn` | string | yes | | | `items[].stay.checkOut` | string | yes | | | `items[].stay.nights` | integer | yes | | | `items[].stay.dayUse` | boolean | yes | | | `items[].guest` | object | yes | | | `items[].guest.fullName` | string | yes | | | `items[].guest.firstName` | string or null | yes | | | `items[].guest.lastName` | string or null | yes | | | `items[].guest.phone` | string or null | no | | | `items[].guest.email` | string or null | no | | | `items[].guest.country` | string or null | yes | | | `items[].guest.language` | string or null | yes | | | `items[].guestNotes` | string or null | yes | | | `items[].occupancy` | object | yes | | | `items[].occupancy.adults` | integer | yes | | | `items[].occupancy.children` | integer | yes | | | `items[].rooms` | array of objects | yes | | | `items[].rooms[].roomTypeId` | integer | yes | | | `items[].rooms[].roomTypeName` | string | yes | | | `items[].rooms[].ratePlanId` | integer or null | no | | | `items[].rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `items[].rooms[].adults` | integer | yes | | | `items[].rooms[].children` | integer | yes | | | `items[].rooms[].checkIn` | string | yes | | | `items[].rooms[].checkOut` | string | yes | | | `items[].rooms[].nights` | integer | yes | | | `items[].rooms[].dayUse` | boolean | yes | | | `items[].rooms[].ratePerNight` | number | yes | | | `items[].rooms[].amount` | number | yes | | | `items[].rooms[].status` | string | yes | | | `items[].amounts` | object | yes | | | `items[].amounts.currency` | string | yes | | | `items[].amounts.total` | number | yes | | | `items[].amounts.paid` | number | yes | | | `items[].amounts.balanceDue` | number | yes | | | `items[].amounts.paymentCollect` | "ota" · "property" · "unknown" | yes | | | `items[].finance` | object or any or null | yes | | | `items[].cancellation` | object or any or null | yes | | | `items[].createdAt` | string | yes | | | `items[].updatedAt` | string | yes | | | `more` | boolean | yes | More rows matched than limit: ask again with cursor = nextCursor | | `nextCursor` | string or null | yes | Pass as cursor for the next page; null when there is no more | Sample answer (`data`): ```json { "since": "2026-10-23T12:00:00.000Z", "items": [ { "id": 100001, "reference": "TEST-ZS-8K3Q2M", "status": "CONFIRMED", "stayStatus": "UPCOMING", "channel": { "otaName": "MakeMyTrip", "otaReservationCode": "TEST-ZS-8K3Q2M", "source": "CHANNEL_MANAGER", "sourceGroup": "INDIRECT" }, "stay": { "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false }, "guest": { "fullName": "Asha Verma", "firstName": "Asha", "lastName": "Verma", "phone": "+919876500000", "email": "asha.verma@example.com", "country": "IN", "language": "en" }, "guestNotes": "Late arrival around 22:00. Non-smoking room please. (test event)", "occupancy": { "adults": 2, "children": 0 }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "roomTypeName": "Deluxe Sea View", "mealPlan": "CP", "adults": 2, "children": 0, "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false, "ratePerNight": 2700, "amount": 5400, "status": "UPCOMING" } ], "amounts": { "currency": "INR", "total": 5400, "paid": 0, "balanceDue": 5400, "paymentCollect": "property" }, "finance": { "otaName": "MakeMyTrip", "amountBasis": "GROSS_TOTAL", "currency": "INR", "grossAmount": 5400, "commissionAmount": 1350, "taxAmount": 648, "netPayoutAmount": 4050 }, "cancellation": null, "createdAt": "2026-10-30T12:00:00.000Z", "updatedAt": "2026-10-30T12:00:00.000Z" } ], "more": false, "nextCursor": null } ``` ### GET /channel-bookings/{bookingId} One channel booking, the webhook's shape. Scope `channel-bookings:read`. Scope channel-bookings:read. 404 for a booking that is not this property's or not a channel booking. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `id` | integer | yes | | | `reference` | string | yes | | | `status` | "CONFIRMED" · "CANCELLED" | yes | | | `stayStatus` | string | yes | | | `channel` | object | yes | | | `channel.otaName` | string | yes | | | `channel.otaReservationCode` | string | yes | | | `channel.source` | string | yes | | | `channel.sourceGroup` | string | yes | | | `stay` | object | yes | | | `stay.checkIn` | string | yes | | | `stay.checkOut` | string | yes | | | `stay.nights` | integer | yes | | | `stay.dayUse` | boolean | yes | | | `guest` | object | yes | | | `guest.fullName` | string | yes | | | `guest.firstName` | string or null | yes | | | `guest.lastName` | string or null | yes | | | `guest.phone` | string or null | no | | | `guest.email` | string or null | no | | | `guest.country` | string or null | yes | | | `guest.language` | string or null | yes | | | `guestNotes` | string or null | yes | | | `occupancy` | object | yes | | | `occupancy.adults` | integer | yes | | | `occupancy.children` | integer | yes | | | `rooms` | array of objects | yes | | | `rooms[].roomTypeId` | integer | yes | | | `rooms[].roomTypeName` | string | yes | | | `rooms[].ratePlanId` | integer or null | no | | | `rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `rooms[].adults` | integer | yes | | | `rooms[].children` | integer | yes | | | `rooms[].checkIn` | string | yes | | | `rooms[].checkOut` | string | yes | | | `rooms[].nights` | integer | yes | | | `rooms[].dayUse` | boolean | yes | | | `rooms[].ratePerNight` | number | yes | | | `rooms[].amount` | number | yes | | | `rooms[].status` | string | yes | | | `amounts` | object | yes | | | `amounts.currency` | string | yes | | | `amounts.total` | number | yes | | | `amounts.paid` | number | yes | | | `amounts.balanceDue` | number | yes | | | `amounts.paymentCollect` | "ota" · "property" · "unknown" | yes | | | `finance` | object or any or null | yes | | | `cancellation` | object or any or null | yes | | | `createdAt` | string | yes | | | `updatedAt` | string | yes | | Sample answer (`data`): ```json { "id": 100001, "reference": "TEST-ZS-8K3Q2M", "status": "CONFIRMED", "stayStatus": "UPCOMING", "channel": { "otaName": "MakeMyTrip", "otaReservationCode": "TEST-ZS-8K3Q2M", "source": "CHANNEL_MANAGER", "sourceGroup": "INDIRECT" }, "stay": { "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false }, "guest": { "fullName": "Asha Verma", "firstName": "Asha", "lastName": "Verma", "phone": "+919876500000", "email": "asha.verma@example.com", "country": "IN", "language": "en" }, "guestNotes": "Late arrival around 22:00. Non-smoking room please. (test event)", "occupancy": { "adults": 2, "children": 0 }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "roomTypeName": "Deluxe Sea View", "mealPlan": "CP", "adults": 2, "children": 0, "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false, "ratePerNight": 2700, "amount": 5400, "status": "UPCOMING" } ], "amounts": { "currency": "INR", "total": 5400, "paid": 0, "balanceDue": 5400, "paymentCollect": "property" }, "finance": { "otaName": "MakeMyTrip", "amountBasis": "GROSS_TOTAL", "currency": "INR", "grossAmount": 5400, "commissionAmount": 1350, "taxAmount": 648, "netPayoutAmount": 4050 }, "cancellation": null, "createdAt": "2026-10-30T12:00:00.000Z", "updatedAt": "2026-10-30T12:00:00.000Z" } ``` ### GET /channels The connected channels and their open issues, from our record. Scope `ari:read`. Scope ari:read. No channel-manager call: asOf is when the list was captured (the nightly settings sweep); open issues are live. Each channel carries its price modifier (x-zimmerstack.modifiers); a modifier set through this API shows at once. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `asOf` | string or null | yes | When the connection list was last captured; null when never | | `channels` | array of objects | yes | | | `channels[].channelId` | string | yes | The channel manager's id for this connection | | `channels[].kind` | string | yes | The channel: BookingCom, Expedia, Agoda, Airbnb, GoMMT, … | | `channels[].title` | string or null | yes | The connection's title in the channel manager | | `channels[].seenAt` | string | yes | When our record last saw this connection (the nightly settings sweep) | | `channels[].openIssues` | array of objects | yes | Unresolved problems the channel manager reported for this connection | | `channels[].openIssues[].event` | string | yes | sync_error · rate_error · disconnect_channel · inventory_out_of_sync · … | | `channels[].openIssues[].raisedAt` | string | yes | | | `channels[].modifier` | array of objects or any or null | yes | This channel's price modifier (§2.8): the steps the channel manager applies, in order, to every price it sends this channel. [] = prices go as they are. null = the channel holds a rule set by hand in the channel manager that this API cannot express; PUT /channels/{channelId}/modifier replaces it | | `channels[].markupPlan` | object or any or null | yes | A separate adjustment the owner set for this channel in the ZimmerStack Channels app, applied before the modifier. Read-only here; null = none | | `propertyIssues` | array of objects | yes | Unresolved problems not tied to one connection (for example the inventory pipe out of sync) | | `propertyIssues[].event` | string | yes | | | `propertyIssues[].raisedAt` | string | yes | | Sample answer (`data`): ```json { "asOf": "2026-10-30T20:15:04.000Z", "channels": [ { "channelId": "7c1d8a3e-5f2b-4d6a-9e0c-1b2a3c4d5e6f", "kind": "BookingCom", "title": "Booking.com — The Lantern House", "seenAt": "2026-10-30T20:15:04.000Z", "openIssues": [], "modifier": [ { "action": "increase", "type": "percent", "value": 18 } ], "markupPlan": null }, { "channelId": "0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d", "kind": "Expedia", "title": "Expedia — The Lantern House", "seenAt": "2026-10-30T20:15:04.000Z", "openIssues": [ { "event": "rate_error", "raisedAt": "2026-10-30T09:40:11.000Z" } ], "modifier": [], "markupPlan": null } ], "propertyIssues": [] } ``` ### GET /direct-bookings The bookings guests made on the hotel's own website, in the webhook's shape. Scope `direct-bookings:read`. Scope direct-bookings:read. The bookings of the ZimmerStack booking engine on this property: the pull beside the direct.booking.* webhooks (x-zimmerstack.directBookings). Oldest change first; since (default the last 7 days) is on the booking's last change so a cancellation is listed again; while more is true, ask again with cursor = nextCursor. A booking deleted in ZimmerStack stays listed, as CANCELLED. Read it before a full availability push. Query: - `since`: Changed on or after this instant (ISO 8601); default: the last 7 days - `status`: Only confirmed or only cancelled; default both - `limit`: Default 50 - `cursor`: The previous page's nextCursor; takes precedence over since. One this API did not issue is 400 VALIDATION Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `since` | string | yes | The instant the list starts at, echoed | | `items` | array of objects | yes | Oldest change first — exactly the booking object the webhooks carry | | `items[].id` | integer | yes | | | `items[].reference` | string | yes | | | `items[].status` | "CONFIRMED" · "CANCELLED" | yes | | | `items[].stayStatus` | string | yes | | | `items[].channel` | object | yes | | | `items[].channel.otaName` | string | yes | | | `items[].channel.otaReservationCode` | string | yes | | | `items[].channel.source` | string | yes | | | `items[].channel.sourceGroup` | string | yes | | | `items[].stay` | object | yes | | | `items[].stay.checkIn` | string | yes | | | `items[].stay.checkOut` | string | yes | | | `items[].stay.nights` | integer | yes | | | `items[].stay.dayUse` | boolean | yes | | | `items[].guest` | object | yes | | | `items[].guest.fullName` | string | yes | | | `items[].guest.firstName` | string or null | yes | | | `items[].guest.lastName` | string or null | yes | | | `items[].guest.phone` | string or null | no | | | `items[].guest.email` | string or null | no | | | `items[].guest.country` | string or null | yes | | | `items[].guest.language` | string or null | yes | | | `items[].guestNotes` | string or null | yes | | | `items[].occupancy` | object | yes | | | `items[].occupancy.adults` | integer | yes | | | `items[].occupancy.children` | integer | yes | | | `items[].rooms` | array of objects | yes | | | `items[].rooms[].roomTypeId` | integer | yes | | | `items[].rooms[].roomTypeName` | string | yes | | | `items[].rooms[].ratePlanId` | integer or null | no | | | `items[].rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `items[].rooms[].adults` | integer | yes | | | `items[].rooms[].children` | integer | yes | | | `items[].rooms[].checkIn` | string | yes | | | `items[].rooms[].checkOut` | string | yes | | | `items[].rooms[].nights` | integer | yes | | | `items[].rooms[].dayUse` | boolean | yes | | | `items[].rooms[].ratePerNight` | number | yes | | | `items[].rooms[].amount` | number | yes | | | `items[].rooms[].status` | string | yes | | | `items[].amounts` | object | yes | | | `items[].amounts.currency` | string | yes | | | `items[].amounts.total` | number | yes | | | `items[].amounts.paid` | number | yes | | | `items[].amounts.balanceDue` | number | yes | | | `items[].amounts.paymentCollect` | "ota" · "property" · "unknown" | yes | | | `items[].finance` | object or any or null | yes | | | `items[].cancellation` | object or any or null | yes | | | `items[].createdAt` | string | yes | | | `items[].updatedAt` | string | yes | | | `more` | boolean | yes | More rows matched than limit: ask again with cursor = nextCursor | | `nextCursor` | string or null | yes | Pass as cursor for the next page; null when there is no more | Sample answer (`data`): ```json { "since": "2026-10-23T12:00:00.000Z", "items": [ { "id": 100001, "reference": "TEST-WEB-4H7P9D", "status": "CONFIRMED", "stayStatus": "UPCOMING", "channel": { "otaName": "Website", "otaReservationCode": "TEST-WEB-4H7P9D", "source": "DIRECT_WEB", "sourceGroup": "DIRECT" }, "stay": { "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false }, "guest": { "fullName": "Asha Verma", "firstName": "Asha", "lastName": "Verma", "phone": "+919876500000", "email": "asha.verma@example.com", "country": "IN", "language": "en" }, "guestNotes": null, "occupancy": { "adults": 2, "children": 0 }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "roomTypeName": "Deluxe Sea View", "mealPlan": "CP", "adults": 2, "children": 0, "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false, "ratePerNight": 2700, "amount": 5400, "status": "UPCOMING" } ], "amounts": { "currency": "INR", "total": 5400, "paid": 1080, "balanceDue": 4320, "paymentCollect": "property" }, "finance": null, "cancellation": null, "createdAt": "2026-10-30T12:00:00.000Z", "updatedAt": "2026-10-30T12:00:00.000Z" } ], "more": false, "nextCursor": null } ``` ### GET /direct-bookings/{bookingId} One website booking, the webhook's shape. Scope `direct-bookings:read`. Scope direct-bookings:read. 404 for a booking that is not this property's or was not made on its website. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `id` | integer | yes | | | `reference` | string | yes | | | `status` | "CONFIRMED" · "CANCELLED" | yes | | | `stayStatus` | string | yes | | | `channel` | object | yes | | | `channel.otaName` | string | yes | | | `channel.otaReservationCode` | string | yes | | | `channel.source` | string | yes | | | `channel.sourceGroup` | string | yes | | | `stay` | object | yes | | | `stay.checkIn` | string | yes | | | `stay.checkOut` | string | yes | | | `stay.nights` | integer | yes | | | `stay.dayUse` | boolean | yes | | | `guest` | object | yes | | | `guest.fullName` | string | yes | | | `guest.firstName` | string or null | yes | | | `guest.lastName` | string or null | yes | | | `guest.phone` | string or null | no | | | `guest.email` | string or null | no | | | `guest.country` | string or null | yes | | | `guest.language` | string or null | yes | | | `guestNotes` | string or null | yes | | | `occupancy` | object | yes | | | `occupancy.adults` | integer | yes | | | `occupancy.children` | integer | yes | | | `rooms` | array of objects | yes | | | `rooms[].roomTypeId` | integer | yes | | | `rooms[].roomTypeName` | string | yes | | | `rooms[].ratePlanId` | integer or null | no | | | `rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `rooms[].adults` | integer | yes | | | `rooms[].children` | integer | yes | | | `rooms[].checkIn` | string | yes | | | `rooms[].checkOut` | string | yes | | | `rooms[].nights` | integer | yes | | | `rooms[].dayUse` | boolean | yes | | | `rooms[].ratePerNight` | number | yes | | | `rooms[].amount` | number | yes | | | `rooms[].status` | string | yes | | | `amounts` | object | yes | | | `amounts.currency` | string | yes | | | `amounts.total` | number | yes | | | `amounts.paid` | number | yes | | | `amounts.balanceDue` | number | yes | | | `amounts.paymentCollect` | "ota" · "property" · "unknown" | yes | | | `finance` | object or any or null | yes | | | `cancellation` | object or any or null | yes | | | `createdAt` | string | yes | | | `updatedAt` | string | yes | | Sample answer (`data`): ```json { "id": 100001, "reference": "TEST-WEB-4H7P9D", "status": "CONFIRMED", "stayStatus": "UPCOMING", "channel": { "otaName": "Website", "otaReservationCode": "TEST-WEB-4H7P9D", "source": "DIRECT_WEB", "sourceGroup": "DIRECT" }, "stay": { "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false }, "guest": { "fullName": "Asha Verma", "firstName": "Asha", "lastName": "Verma", "phone": "+919876500000", "email": "asha.verma@example.com", "country": "IN", "language": "en" }, "guestNotes": null, "occupancy": { "adults": 2, "children": 0 }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "roomTypeName": "Deluxe Sea View", "mealPlan": "CP", "adults": 2, "children": 0, "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false, "ratePerNight": 2700, "amount": 5400, "status": "UPCOMING" } ], "amounts": { "currency": "INR", "total": 5400, "paid": 1080, "balanceDue": 4320, "paymentCollect": "property" }, "finance": null, "cancellation": null, "createdAt": "2026-10-30T12:00:00.000Z", "updatedAt": "2026-10-30T12:00:00.000Z" } ``` ### GET /properties The properties this key may act on. Any key. A company key: every hotel it may act on, with the id to name in the X-ZS-Property header; the one route a company key calls without that header. A hotel key: its own property, in the same shape. keyKind says which kind of key you hold. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `keyKind` | "company" · "property" | yes | company: a software vendor's key, the hotel named in X-ZS-Property on every request. property: one hotel's own key, no header needed. | | `properties` | array of objects | yes | A company key: every property it may act on. A hotel key: its one property. | | `properties[].id` | integer | yes | The id a company key names in the X-ZS-Property header | | `properties[].name` | string | yes | | | `properties[].timezone` | string | yes | | | `properties[].currency` | string | yes | | | `properties[].channelManager` | boolean | yes | The property publishes to its channels | | `properties[].sandbox` | boolean | yes | A sandbox: everything lands locally, nothing reaches a channel | Sample answer (`data`): ```json { "keyKind": "company", "properties": [ { "id": 61, "name": "The Lantern House", "timezone": "Asia/Kolkata", "currency": "INR", "channelManager": true, "sandbox": false }, { "id": 62, "name": "Hill View Retreat", "timezone": "Asia/Kolkata", "currency": "INR", "channelManager": true, "sandbox": false } ] } ``` ### GET /property The property this key is for. Any key. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `id` | integer | yes | | | `name` | string | yes | | | `timezone` | string | yes | IANA; every date in this API is a calendar date in this zone | | `currency` | string | yes | ISO 4217; every rate must be sent in it | | `inventoryScope` | "PMS_CM" · "CM_ONLY" · "PMS_CUTOVER" · "OWNER_SITE" | yes | | | `sandbox` | boolean | yes | true when this key is a zsk_test_ key on the owner's sandbox: nothing you send reaches a channel, and POST /sandbox/bookings simulates an OTA booking | | `horizonDays` | integer | yes | last writable night = today + horizonDays | | `ariAuthoritative` | boolean | yes | | | `scopes` | array of string | yes | what THIS key may do: ari:read · ari:write · bookings:read · bookings:write · bookings:payments | | `products` | object | yes | | | `products.channelManager` | boolean | yes | the ARI routes need it | | `products.pms` | boolean | yes | the booking routes need it | | `limits` | object | yes | | | `limits.requestsPerMinute` | integer | yes | | | `limits.writesPerMinute` | integer | yes | | | `limits.maxUpdatesPerRequest` | integer | yes | | | `limits.maxCellsPerRequest` | integer | yes | | | `limits.bookingsPerMinute` | integer | yes | | | `limits.cellsPerHour` | integer | yes | Changed cells this property may take per clock hour (UTC), all its keys together. A cell that already holds the value sent is not counted | | `limits.cellsPerDay` | integer | yes | Changed cells this property may take per rolling 24 hours | | `limits.maxRoomTypes` | integer | yes | Room types this property may hold | | `limits.maxRatePlans` | integer | yes | Rate plans this property may hold | | `limits.ratePlansPerRoomType` | integer or null | yes | A vacation rental: rate plans this property may hold per room type, counted over the whole property. null on a hotel, where maxRatePlans is the rule | | `limits.newEntitiesPerMinute` | integer | yes | New room types or rate plans one request, and one minute, may create | | `usage` | object | yes | What this property has used of its long budgets (§6.6) | | `usage.cellsThisHour` | integer | yes | Changed cells counted against cellsPerHour so far this clock hour | | `usage.cellsLast24h` | integer | yes | Changed cells counted against cellsPerDay over the last 24 hours | | `shield` | object | yes | Where this integration stands with the channel shield. Reads and bookings are never affected | | `shield.level` | "CLEAR" · "WATCH" · "PAUSED" · "SUSPENDED" | yes | CLEAR nothing held against the integration · WATCH noted, nothing refused · PAUSED only writes that close inventory are accepted · SUSPENDED every write refused until ZimmerStack releases it | | `shield.reason` | string or null | yes | Why, when the level is not CLEAR | | `shield.until` | string or null | yes | When a pause ends on its own (ISO instant); null = until released, or not paused | | `sync` | object | yes | | | `sync.state` | "IN_SYNC" · "PENDING" · "OUT_OF_SYNC" · "DISABLED" | yes | | | `sync.pendingCells` | integer | yes | | Sample answer (`data`): ```json { "id": 61, "name": "The Lantern House", "timezone": "Asia/Kolkata", "currency": "INR", "inventoryScope": "PMS_CM", "sandbox": false, "horizonDays": 365, "ariAuthoritative": true, "scopes": [ "bookings:read", "bookings:write" ], "products": { "channelManager": true, "pms": true }, "limits": { "requestsPerMinute": 120, "writesPerMinute": 30, "maxUpdatesPerRequest": 1000, "maxCellsPerRequest": 5000, "bookingsPerMinute": 20, "cellsPerHour": 10000, "cellsPerDay": 30000, "maxRoomTypes": 18, "maxRatePlans": 180, "ratePlansPerRoomType": null, "newEntitiesPerMinute": 20 }, "usage": { "cellsThisHour": 43, "cellsLast24h": 1138 }, "shield": { "level": "CLEAR", "reason": null, "until": null }, "sync": { "state": "IN_SYNC", "pendingCells": 0 } } ``` ### GET /rates Rates as our record holds them (minor units). Scope `ari:read`. Served from our record, never from the channel manager. Query: - `from`: Default: today in the property's timezone - `to`: Default: from + 30 days; at most 500 days after from Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `from` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `to` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `currency` | string | yes | | | `cells` | array of objects | yes | | | `cells[].ratePlanId` | integer | yes | | | `cells[].date` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `cells[].rateMinor` | integer | yes | MINOR units (paise, cents) | | `cells[].source` | "MANUAL" · "BASE" · "ENGINE" · "CHANNEX_SEED" · "PLAN_DEFAULT" · "STANDING" | yes | | ### GET /restrictions Restrictions as our record holds them. Scope `ari:read`. null = we hold no opinion for that field on that night. Query: - `from`: Default: today in the property's timezone - `to`: Default: from + 30 days; at most 500 days after from Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `from` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `to` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `cells` | array of objects | yes | | | `cells[].ratePlanId` | integer | yes | | | `cells[].date` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `cells[].stopSell` | boolean or null | yes | | | `cells[].closedToArrival` | boolean or null | yes | | | `cells[].closedToDeparture` | boolean or null | yes | | | `cells[].minStayArrival` | integer or null | yes | | | `cells[].minStayThrough` | integer or null | yes | | | `cells[].maxStay` | integer or null | yes | | ### GET /sandbox/bookings Simulated OTA bookings on the sandbox, newest first. Scope `ari:read`. Scope ari:read, test keys only (403 SANDBOX_ONLY on a live key). Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookings` | array of objects | yes | Simulated bookings on the sandbox (OTA and website), newest first | | `bookings[].bookingId` | integer | yes | The PMS booking id, the one the webhook carries | | `bookings[].reference` | string | yes | The booking reference, SBX-… — the webhook's booking.reference | | `bookings[].channelBookingId` | string | yes | The pretend channel-side id | | `bookings[].otaName` | string | yes | | | `bookings[].status` | "UPCOMING" · "CANCELLED" | yes | | | `bookings[].guestName` | string | yes | | | `bookings[].checkIn` | string | yes | | | `bookings[].checkOut` | string | yes | | | `bookings[].nights` | integer | yes | | | `bookings[].rooms` | integer | yes | | | `bookings[].roomTypeId` | integer | yes | | | `bookings[].nightlyRate` | number | yes | Major units, per room per night | | `bookings[].total` | number | yes | Major units | | `bookings[].currency` | string | yes | | | `bookings[].paidByOta` | boolean | yes | | | `bookings[].oversold` | boolean | yes | true when a night had no sandbox availability left — the booking lands anyway, as an OTA booking would | | `bookings[].createdAt` | string | yes | | | `bookings[].webhook` | object | yes | What this call put on the wire for the sandbox's webhook endpoints | | `bookings[].webhook.eventType` | "channel.booking.created" · "channel.booking.modified" · "channel.booking.cancelled" · "direct.booking.created" · "direct.booking.cancelled" | yes | | | `bookings[].webhook.queued` | boolean | yes | The event is in the outbox; every active endpoint on the sandbox receives it within seconds | Sample answer (`data`): ```json { "bookings": [ { "bookingId": 90311, "reference": "SBX-9001-MH3K2Q7A", "channelBookingId": "sbx-1f6d0c2e-7b53-4a0e-9c5a-2d8f3b1e4c70", "otaName": "Booking.com", "status": "UPCOMING", "guestName": "Asha Verma", "checkIn": "2026-12-05", "checkOut": "2026-12-07", "nights": 2, "rooms": 1, "roomTypeId": 412, "nightlyRate": 4500, "total": 9000, "currency": "INR", "paidByOta": false, "oversold": false, "createdAt": "2026-10-30T12:00:00.000Z", "webhook": { "eventType": "channel.booking.created", "queued": true } } ] } ``` ### GET /sync Has what you sent reached the channels?. Scope `ari:read`. Poll this instead of asking the channel manager: inventory pipe state, rate cells still queued, the projector's last outcome and the newest batch still pending. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `propertyId` | integer | yes | | | `sandbox` | boolean | yes | true on a sandbox property (a zsk_test_ key): pushes land in our record and stop there, so IN_SYNC means recorded | | `ariAuthoritative` | boolean | yes | false = nothing is pushed; ask ZimmerStack support | | `inventory` | object | yes | | | `inventory.state` | "IN_SYNC" · "PENDING" · "OUT_OF_SYNC" · "DISABLED" | yes | | | `inventory.pendingCells` | integer | yes | | | `inventory.lastOkAt` | string or null | yes | | | `inventory.lastError` | string or null | yes | | | `inventory.outOfSyncSince` | string or null | yes | | | `rates` | object | yes | | | `rates.dirtyCells` | integer | yes | rate/restriction cells waiting for the projector | | `rates.parkedCells` | integer | yes | rate/restriction cells the channel manager refused: held, no longer re-sent, their batch reads failed. Send a corrected value for those nights (§6.6) | | `rates.lastPushAt` | string or null | yes | | | `rates.lastErrorAt` | string or null | yes | | | `rates.lastError` | string or null | yes | | | `shield` | object | yes | Where this integration stands with the channel shield. Reads and bookings are never affected | | `shield.level` | "CLEAR" · "WATCH" · "PAUSED" · "SUSPENDED" | yes | CLEAR nothing held against the integration · WATCH noted, nothing refused · PAUSED only writes that close inventory are accepted · SUSPENDED every write refused until ZimmerStack releases it | | `shield.reason` | string or null | yes | Why, when the level is not CLEAR | | `shield.until` | string or null | yes | When a pause ends on its own (ISO instant); null = until released, or not paused | | `newestPendingBatch` | object or any or null | yes | | ### PUT /availability Set absolute availability. Scope `ari:write`. Each update sets the ABSOLUTE number of rooms for sale for one room type over a date range. Lands in our record and rides the inventory drain to the channels. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `updates` | array of objects | yes | | | `updates[].roomTypeId` | integer | yes | ZimmerStack room type id (GET /catalog) | | `updates[].dateFrom` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `updates[].dateTo` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `updates[].available` | integer | yes | ABSOLUTE count of rooms of this type for sale on each night of the range | Sample body: ```json { "updates": [ { "roomTypeId": 412, "dateFrom": "2026-11-01", "dateTo": "2026-11-30", "available": 5 }, { "roomTypeId": 412, "dateFrom": "2026-11-14", "dateTo": "2026-11-14", "available": 2 } ] } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `batchId` | string (uuid) | yes | | | `resource` | "availability" · "rates" · "restrictions" | yes | | | `requestedCells` | integer | yes | distinct cells after per-request coalescing (last write wins) | | `acceptedCells` | integer | yes | cells that differed from our record and were written; they will be pushed | | `noopCells` | integer | yes | cells that already held the requested value; nothing written, nothing pushed | | `rejected` | array of objects | yes | groups our record refused (e.g. a plan whose policy forbids exceptions) | | `rejected[].cells` | integer | yes | | | `rejected[].error` | string | yes | | | `pushedBy` | "inventory-drain" · "ari-projector" | yes | | | `poll` | string | yes | GET path to watch this batch land | | `warnings` | array of objects | no | Accepted, but worth a look: an availability above the room type's room count (an oversell the channels will sell). Absent when there is nothing to say | | `warnings[].roomTypeId` | integer | yes | | | `warnings[].units` | integer | yes | Rooms of this type in our record | | `warnings[].requested` | integer | yes | The highest count this request set for it | | `warnings[].message` | string | yes | | | `priceWarnings` | array of objects | no | Accepted, but far outside the plan's standing price, on a property whose price band only warns (§6.6). At most 20; absent when there is nothing to say | | `priceWarnings[].ratePlanId` | integer | yes | | | `priceWarnings[].date` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `priceWarnings[].rateMinor` | integer | yes | The price this request set, MINOR units | | `priceWarnings[].standingMinor` | integer | yes | The plan's standing price, MINOR units | | `priceWarnings[].message` | string | yes | | | `lane` | boolean | no | true when the write was taken through the safety lane: the integration is paused or over a budget, and this write only closed inventory (§6.6) | Sample answer (`data`): ```json { "batchId": "7f1d2c4e-5a6b-4c8d-9e0f-112233445566", "resource": "rates", "requestedCells": 151, "acceptedCells": 43, "noopCells": 108, "rejected": [], "pushedBy": "ari-projector", "poll": "/api/v1/connect-api/v1/batches/7f1d2c4e-5a6b-4c8d-9e0f-112233445566" } ``` ### PUT /catalog/rate-plans Create or change rate plans by your own ref. Scope `catalog:write`. Scope catalog:write. Up to 100 per request, each ref once; name the room type by our id (roomTypeId) or by the ref you gave it (roomTypeRef, in this request or an earlier one). A ref seen before is updated where the fields differ; a new ref whose name exists under the same room type (with no ref) adopts that plan; anything else is created here and on the channel manager at once, seeded at defaultRateMinor when given. A plan never moves between room types. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `ratePlans` | array of objects | yes | Each ref once per request | | `ratePlans[].ref` | string | yes | Your own id for this entity: the upsert key, stable across sends (1–64 of A–Z a–z 0–9 . _ : -) | | `ratePlans[].roomTypeId` | integer | no | The room type this plan sells (GET /catalog); or name it by roomTypeRef | | `ratePlans[].roomTypeRef` | string | no | The room type by the ref you gave it, in this request or an earlier one | | `ratePlans[].name` | string | yes | Shown to the owner and sent to the channel manager as the title | | `ratePlans[].mealPlan` | "EP" · "CP" · "MAP" · "AP" or any or null | no | EP room only · CP breakfast · MAP half board · AP full board; null = not set | | `ratePlans[].occupancy` | integer or any or null | no | The occupancy this plan is priced for; null = the room type's default | | `ratePlans[].refundable` | boolean | no | false = a non-refundable plan; default true | | `ratePlans[].defaultRate` | number or string or any or null | no | The plan's standing price in MAJOR units (e.g. 4500 or "4500.00"), like every rate here: what new dates open at, mirrored to the channel manager. Omit to leave it; null = follow the room type's base rate | | `ratePlans[].defaultRateMinor` | integer or any or null | no | Deprecated: the same standing price in MINOR units (paise). Send defaultRate instead; never both | Sample body: ```json { "ratePlans": [ { "ref": "rp-bb", "roomTypeRef": "rt-deluxe", "name": "Bed and breakfast", "mealPlan": "CP", "occupancy": 2, "refundable": true, "defaultRateMinor": 450000 }, { "ref": "rp-ph-ro", "roomTypeRef": "rt-penthouse", "name": "Room only", "mealPlan": "EP", "occupancy": 3, "refundable": false, "defaultRateMinor": 1200000 } ] } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `items` | array of objects | yes | One per entity sent, in the order sent | | `items[].ref` | string | yes | | | `items[].id` | integer | yes | The ZimmerStack id: what every availability, rate and booking write names from now on | | `items[].action` | "created" · "updated" · "adopted" · "unchanged" | yes | created: new here and on the channel manager · updated: fields changed · adopted: an entity the owner had already made with this name is now yours by ref · unchanged: nothing differed | | `items[].sync` | string (7 values) | yes | IN_SYNC the channel manager has it · PENDING / SENDING on its way · FAILED stopped retrying (the owner's screen offers Retry) · DRIFTED someone changed it inside the channel manager · NOT_LINKED saved here, never added there · DISABLED the property is not connected | | `items[].notice` | string or null | yes | Saved, but something to know (for example the property is not on the channel manager yet); null when nothing | | `channelManager` | object | yes | Where the property stands after this write; a sandbox always says enabled | | `channelManager.enabled` | boolean | yes | The property publishes to its channels | | `channelManager.reason` | string or null | yes | Why not, when enabled is false (for example: a room type still has no rate plan) | Sample answer (`data`): ```json { "items": [ { "ref": "rt-deluxe", "id": 412, "action": "adopted", "sync": "IN_SYNC", "notice": null }, { "ref": "rt-penthouse", "id": 414, "action": "created", "sync": "IN_SYNC", "notice": null } ], "channelManager": { "enabled": true, "reason": null } } ``` ### DELETE /catalog/rate-plans/{ratePlanId} Delete a rate plan: the channel manager's copy first, then ours. Scope `catalog:write`. Scope catalog:write. Refused while a channel still sells it (unmap it on the channel manager first). Nothing changes here when the channel manager refuses. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `id` | integer | yes | | | `deleted` | true | yes | | | `channelManagerDeleted` | boolean | yes | The channel manager's copy is gone too (a sandbox has none) | | `deletedRatePlanIds` | array of integer | yes | For a room type: the plans that went with it | Sample answer (`data`): ```json { "id": 903, "deleted": true, "channelManagerDeleted": true, "deletedRatePlanIds": [] } ``` ### PUT /catalog/room-types Create or change room types by your own ref. Scope `catalog:write`. Scope catalog:write. Up to 50 per request, each ref once. A ref seen before is updated where the fields differ; a new ref whose name the owner already used (with no ref) adopts that room type; anything else is created here and on the channel manager at once. roomCount is read at creation only. The answer lists our id, the action and the sync status per entity, and where the property's channel manager stands. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `roomTypes` | array of objects | yes | Each ref once per request | | `roomTypes[].ref` | string | yes | Your own id for this entity: the upsert key, stable across sends (1–64 of A–Z a–z 0–9 . _ : -) | | `roomTypes[].name` | string | yes | Shown to the owner and sent to the channel manager as the title | | `roomTypes[].roomCount` | integer | yes | Sellable rooms of this type. On a channel-manager-only hotel a later change is written too, to the channel manager first (its count caps what the channels sell); a count below the rooms holding upcoming stays is refused. On a hotel that runs our PMS the count comes from its room list and a different value is not written (the answer's notice says so) | | `roomTypes[].adults` | integer | yes | Most adults one room takes | | `roomTypes[].children` | integer | no | Most children one room takes; default 0 | Sample body: ```json { "roomTypes": [ { "ref": "rt-deluxe", "name": "Deluxe Garden Room", "roomCount": 8, "adults": 2, "children": 1 }, { "ref": "rt-penthouse", "name": "Penthouse", "roomCount": 1, "adults": 3, "children": 1 } ] } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `items` | array of objects | yes | One per entity sent, in the order sent | | `items[].ref` | string | yes | | | `items[].id` | integer | yes | The ZimmerStack id: what every availability, rate and booking write names from now on | | `items[].action` | "created" · "updated" · "adopted" · "unchanged" | yes | created: new here and on the channel manager · updated: fields changed · adopted: an entity the owner had already made with this name is now yours by ref · unchanged: nothing differed | | `items[].sync` | string (7 values) | yes | IN_SYNC the channel manager has it · PENDING / SENDING on its way · FAILED stopped retrying (the owner's screen offers Retry) · DRIFTED someone changed it inside the channel manager · NOT_LINKED saved here, never added there · DISABLED the property is not connected | | `items[].notice` | string or null | yes | Saved, but something to know (for example the property is not on the channel manager yet); null when nothing | | `channelManager` | object | yes | Where the property stands after this write; a sandbox always says enabled | | `channelManager.enabled` | boolean | yes | The property publishes to its channels | | `channelManager.reason` | string or null | yes | Why not, when enabled is false (for example: a room type still has no rate plan) | Sample answer (`data`): ```json { "items": [ { "ref": "rt-deluxe", "id": 412, "action": "adopted", "sync": "IN_SYNC", "notice": null }, { "ref": "rt-penthouse", "id": 414, "action": "created", "sync": "IN_SYNC", "notice": null } ], "channelManager": { "enabled": true, "reason": null } } ``` ### DELETE /catalog/room-types/{roomTypeId} Delete a room type: the channel manager's copy first, then ours; its plans go with it. Scope `catalog:write`. Scope catalog:write. Refused while rooms are assigned to it on a PMS property, or while a channel still sells one of its plans. Nothing changes here when the channel manager refuses. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `id` | integer | yes | | | `deleted` | true | yes | | | `channelManagerDeleted` | boolean | yes | The channel manager's copy is gone too (a sandbox has none) | | `deletedRatePlanIds` | array of integer | yes | For a room type: the plans that went with it | Sample answer (`data`): ```json { "id": 414, "deleted": true, "channelManagerDeleted": true, "deletedRatePlanIds": [ 903 ] } ``` ### PUT /channels/{channelId}/modifier Set one channel's price modifier. Scope `channel-modifiers:write`. Scope channel-modifiers:write. Replaces the channel's steps with the list sent ([] removes them). Applied to the channel manager while the request runs, read back, then answered: 200 means the channel holds them. Takes effect on prices sent to the channel after the change; prices already there stay until sent again (POST /rates/resend). Steps the channel already holds answer changed: false and cost nothing. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `steps` | array of objects | yes | The whole modifier, in the order it is applied; replaces what the channel holds. At most 5 steps. An empty list removes it: prices go to the channel as they are | | `steps[].action` | "increase" · "decrease" | yes | Raise or lower what this channel is sent | | `steps[].type` | "percent" · "fixed" | yes | percent of the price, or a fixed amount in MAJOR units of the property's currency | | `steps[].value` | number | yes | How much: 18 with type percent is 18 %; 200 with type fixed is 200.00 in the property's currency. Always positive: choose decrease instead of a minus sign. Two decimals at most | Sample body: ```json { "steps": [ { "action": "increase", "type": "percent", "value": 18 }, { "action": "decrease", "type": "fixed", "value": 200 } ] } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `channelId` | string | yes | | | `kind` | string | yes | The channel: BookingCom, Expedia, Agoda, Airbnb, GoMMT, … | | `title` | string or null | yes | | | `modifier` | array of objects | yes | What the channel holds now | | `modifier[].action` | "increase" · "decrease" | yes | Raise or lower what this channel is sent | | `modifier[].type` | "percent" · "fixed" | yes | percent of the price, or a fixed amount in MAJOR units of the property's currency | | `modifier[].value` | number | yes | How much: 18 with type percent is 18 %; 200 with type fixed is 200.00 in the property's currency. Always positive: choose decrease instead of a minus sign. Two decimals at most | | `changed` | boolean | yes | false when the channel already held exactly these steps: nothing was sent to the channel manager and nothing was counted | | `notice` | string | yes | When it takes effect. Always: "A modifier applies to prices sent to the channel after the change. Prices already on the channel stay as they are until those nights are sent again." | Sample answer (`data`): ```json { "channelId": "7c1d8a3e-5f2b-4d6a-9e0c-1b2a3c4d5e6f", "kind": "BookingCom", "title": "Booking.com — The Lantern House", "modifier": [ { "action": "increase", "type": "percent", "value": 18 }, { "action": "decrease", "type": "fixed", "value": 200 } ], "changed": true, "notice": "A modifier applies to prices sent to the channel after the change. Prices already on the channel stay as they are until those nights are sent again." } ``` ### PUT /rates Set nightly sell prices. Scope `ari:write`. Each update sets the price of one rate plan over a date range, optionally masked to weekdays (`days`). `currency` must equal the property's. Lands in our record and rides the ARI projector to the channels. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `updates` | array of objects | yes | | | `updates[].ratePlanId` | integer | yes | ZimmerStack rate plan id (GET /catalog) | | `updates[].dateFrom` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `updates[].dateTo` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `updates[].days` | array of string (7 values) | no | | | `updates[].rate` | number or string | yes | Nightly sell price in MAJOR units (e.g. 4500 or "4500.00"), 1 to 21474836; rounded to a whole major unit | | `updates[].currency` | string | yes | ISO 4217; must equal the property's currency (GET /property) | Sample body: ```json { "updates": [ { "ratePlanId": 901, "dateFrom": "2026-11-01", "dateTo": "2027-03-31", "rate": "4500.00", "currency": "INR" }, { "ratePlanId": 901, "dateFrom": "2026-11-01", "dateTo": "2027-03-31", "days": [ "fr", "sa" ], "rate": 5200, "currency": "INR" } ] } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `batchId` | string (uuid) | yes | | | `resource` | "availability" · "rates" · "restrictions" | yes | | | `requestedCells` | integer | yes | distinct cells after per-request coalescing (last write wins) | | `acceptedCells` | integer | yes | cells that differed from our record and were written; they will be pushed | | `noopCells` | integer | yes | cells that already held the requested value; nothing written, nothing pushed | | `rejected` | array of objects | yes | groups our record refused (e.g. a plan whose policy forbids exceptions) | | `rejected[].cells` | integer | yes | | | `rejected[].error` | string | yes | | | `pushedBy` | "inventory-drain" · "ari-projector" | yes | | | `poll` | string | yes | GET path to watch this batch land | | `warnings` | array of objects | no | Accepted, but worth a look: an availability above the room type's room count (an oversell the channels will sell). Absent when there is nothing to say | | `warnings[].roomTypeId` | integer | yes | | | `warnings[].units` | integer | yes | Rooms of this type in our record | | `warnings[].requested` | integer | yes | The highest count this request set for it | | `warnings[].message` | string | yes | | | `priceWarnings` | array of objects | no | Accepted, but far outside the plan's standing price, on a property whose price band only warns (§6.6). At most 20; absent when there is nothing to say | | `priceWarnings[].ratePlanId` | integer | yes | | | `priceWarnings[].date` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `priceWarnings[].rateMinor` | integer | yes | The price this request set, MINOR units | | `priceWarnings[].standingMinor` | integer | yes | The plan's standing price, MINOR units | | `priceWarnings[].message` | string | yes | | | `lane` | boolean | no | true when the write was taken through the safety lane: the integration is paused or over a budget, and this write only closed inventory (§6.6) | Sample answer (`data`): ```json { "batchId": "7f1d2c4e-5a6b-4c8d-9e0f-112233445566", "resource": "rates", "requestedCells": 151, "acceptedCells": 43, "noopCells": 108, "rejected": [], "pushedBy": "ari-projector", "poll": "/api/v1/connect-api/v1/batches/7f1d2c4e-5a6b-4c8d-9e0f-112233445566" } ``` ### POST /rates/resend Send the property's prices to the channels again. Scope `ari:write`. Scope ari:write. Marks every rate-plan night of the writable horizon to be sent again, unchanged, so each channel's current modifier applies to it. The nights travel like any write: paced, coalesced, never lost. Use it after changing a modifier; it is limited per property per day (data.scope rate-resends-day). No body. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `from` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `to` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `cells` | integer | yes | Rate-plan nights marked to be sent again. They travel like any write: watch rates.dirtyCells on GET /sync fall to 0 | | `parkedLeft` | integer | yes | Nights left out because the channel manager refused their value earlier (rates.parkedCells on GET /sync): send a corrected value for those | | `watch` | string | yes | GET path that says when it has landed | | `notice` | string | yes | | Sample answer (`data`): ```json { "from": "2026-11-12", "to": "2027-11-12", "cells": 1098, "parkedLeft": 0, "watch": "/api/v1/connect-api/v1/sync", "notice": "The prices and stay rules of these nights are on their way to the channels again, unchanged, at the usual pace. A full calendar takes minutes." } ``` ### PUT /restrictions Set stay restrictions. Scope `ari:write`. Each update sets ANY subset of stopSell, closedToArrival, closedToDeparture, minStayArrival, minStayThrough, maxStay for one rate plan over a date range; fields you omit are left as they are. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `updates` | array of objects | yes | | | `updates[].ratePlanId` | integer | yes | ZimmerStack rate plan id (GET /catalog) | | `updates[].dateFrom` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `updates[].dateTo` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `updates[].days` | array of string (7 values) | no | | | `updates[].stopSell` | boolean | no | | | `updates[].closedToArrival` | boolean | no | | | `updates[].closedToDeparture` | boolean | no | | | `updates[].minStayArrival` | integer | no | | | `updates[].minStayThrough` | integer | no | | | `updates[].maxStay` | integer | no | | Sample body: ```json { "updates": [ { "ratePlanId": 901, "dateFrom": "2026-12-24", "dateTo": "2026-12-26", "minStayArrival": 2, "closedToArrival": false }, { "ratePlanId": 901, "dateFrom": "2026-12-31", "dateTo": "2026-12-31", "stopSell": true } ] } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `batchId` | string (uuid) | yes | | | `resource` | "availability" · "rates" · "restrictions" | yes | | | `requestedCells` | integer | yes | distinct cells after per-request coalescing (last write wins) | | `acceptedCells` | integer | yes | cells that differed from our record and were written; they will be pushed | | `noopCells` | integer | yes | cells that already held the requested value; nothing written, nothing pushed | | `rejected` | array of objects | yes | groups our record refused (e.g. a plan whose policy forbids exceptions) | | `rejected[].cells` | integer | yes | | | `rejected[].error` | string | yes | | | `pushedBy` | "inventory-drain" · "ari-projector" | yes | | | `poll` | string | yes | GET path to watch this batch land | | `warnings` | array of objects | no | Accepted, but worth a look: an availability above the room type's room count (an oversell the channels will sell). Absent when there is nothing to say | | `warnings[].roomTypeId` | integer | yes | | | `warnings[].units` | integer | yes | Rooms of this type in our record | | `warnings[].requested` | integer | yes | The highest count this request set for it | | `warnings[].message` | string | yes | | | `priceWarnings` | array of objects | no | Accepted, but far outside the plan's standing price, on a property whose price band only warns (§6.6). At most 20; absent when there is nothing to say | | `priceWarnings[].ratePlanId` | integer | yes | | | `priceWarnings[].date` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `priceWarnings[].rateMinor` | integer | yes | The price this request set, MINOR units | | `priceWarnings[].standingMinor` | integer | yes | The plan's standing price, MINOR units | | `priceWarnings[].message` | string | yes | | | `lane` | boolean | no | true when the write was taken through the safety lane: the integration is paused or over a budget, and this write only closed inventory (§6.6) | Sample answer (`data`): ```json { "batchId": "7f1d2c4e-5a6b-4c8d-9e0f-112233445566", "resource": "rates", "requestedCells": 151, "acceptedCells": 43, "noopCells": 108, "rejected": [], "pushedBy": "ari-projector", "poll": "/api/v1/connect-api/v1/batches/7f1d2c4e-5a6b-4c8d-9e0f-112233445566" } ``` ### POST /sandbox/bookings Simulate an OTA booking on the sandbox: the booking, the inventory, the real webhook. Scope `ari:write`. Scope ari:write, test keys only (403 SANDBOX_ONLY on a live key). Creates a channel booking on the sandbox exactly as the channel manager would: the booking row, the room type's availability moved down for every night, the inventory event, and the channel.booking.created webhook queued to every endpoint registered on the sandbox. A sold-out night does not refuse (an OTA oversells; the PMS is told): the booking lands with oversold: true. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `roomTypeId` | integer | yes | A room type of the sandbox (GET /catalog) | | `checkIn` | string | yes | Arrival, YYYY-MM-DD in the property's timezone; today or later, within the horizon | | `nights` | integer | yes | 1–30; checkout = checkIn + nights | | `rooms` | integer | no | Rooms of this type the guest books (1–5); default 1 | | `adults` | integer | no | Adults per room; default 2 | | `guestName` | string | no | The guest's name; default a fictional one | | `otaName` | string (7 values) | no | The channel the booking pretends to arrive from; default Booking.com. "Website" simulates a booking on the hotel's own website (our booking engine): it sends direct.booking.created and is listed by GET /direct-bookings, not GET /channel-bookings | | `paidByOta` | boolean | no | true = the channel collected the money (for Website: the guest paid online), so totalPaid equals the total; default false (pay at the property) | Sample body: ```json { "roomTypeId": 412, "checkIn": "2026-12-05", "nights": 2, "rooms": 1, "adults": 2, "guestName": "Asha Verma", "otaName": "Booking.com", "paidByOta": false } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookingId` | integer | yes | The PMS booking id, the one the webhook carries | | `reference` | string | yes | The booking reference, SBX-… — the webhook's booking.reference | | `channelBookingId` | string | yes | The pretend channel-side id | | `otaName` | string | yes | | | `status` | "UPCOMING" · "CANCELLED" | yes | | | `guestName` | string | yes | | | `checkIn` | string | yes | | | `checkOut` | string | yes | | | `nights` | integer | yes | | | `rooms` | integer | yes | | | `roomTypeId` | integer | yes | | | `nightlyRate` | number | yes | Major units, per room per night | | `total` | number | yes | Major units | | `currency` | string | yes | | | `paidByOta` | boolean | yes | | | `oversold` | boolean | yes | true when a night had no sandbox availability left — the booking lands anyway, as an OTA booking would | | `createdAt` | string | yes | | | `webhook` | object | yes | What this call put on the wire for the sandbox's webhook endpoints | | `webhook.eventType` | "channel.booking.created" · "channel.booking.modified" · "channel.booking.cancelled" · "direct.booking.created" · "direct.booking.cancelled" | yes | | | `webhook.queued` | boolean | yes | The event is in the outbox; every active endpoint on the sandbox receives it within seconds | Sample answer (`data`): ```json { "bookingId": 90311, "reference": "SBX-9001-MH3K2Q7A", "channelBookingId": "sbx-1f6d0c2e-7b53-4a0e-9c5a-2d8f3b1e4c70", "otaName": "Booking.com", "status": "UPCOMING", "guestName": "Asha Verma", "checkIn": "2026-12-05", "checkOut": "2026-12-07", "nights": 2, "rooms": 1, "roomTypeId": 412, "nightlyRate": 4500, "total": 9000, "currency": "INR", "paidByOta": false, "oversold": false, "createdAt": "2026-10-30T12:00:00.000Z", "webhook": { "eventType": "channel.booking.created", "queued": true } } ``` ### POST /sandbox/bookings/{bookingId}/cancel The channel cancels a simulated booking: availability back, the real cancelled webhook. Scope `ari:write`. Scope ari:write, test keys only (403 SANDBOX_ONLY on a live key). Idempotent: an already-cancelled booking answers 200 with webhook.queued false. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookingId` | integer | yes | The PMS booking id, the one the webhook carries | | `reference` | string | yes | The booking reference, SBX-… — the webhook's booking.reference | | `channelBookingId` | string | yes | The pretend channel-side id | | `otaName` | string | yes | | | `status` | "UPCOMING" · "CANCELLED" | yes | | | `guestName` | string | yes | | | `checkIn` | string | yes | | | `checkOut` | string | yes | | | `nights` | integer | yes | | | `rooms` | integer | yes | | | `roomTypeId` | integer | yes | | | `nightlyRate` | number | yes | Major units, per room per night | | `total` | number | yes | Major units | | `currency` | string | yes | | | `paidByOta` | boolean | yes | | | `oversold` | boolean | yes | true when a night had no sandbox availability left — the booking lands anyway, as an OTA booking would | | `createdAt` | string | yes | | | `webhook` | object | yes | What this call put on the wire for the sandbox's webhook endpoints | | `webhook.eventType` | "channel.booking.created" · "channel.booking.modified" · "channel.booking.cancelled" · "direct.booking.created" · "direct.booking.cancelled" | yes | | | `webhook.queued` | boolean | yes | The event is in the outbox; every active endpoint on the sandbox receives it within seconds | ### POST /sandbox/bookings/{bookingId}/modify The channel sends a modified revision: new dates, length, rooms or guest; the real modified webhook. Scope `ari:write`. Scope ari:write, test keys only (403 SANDBOX_ONLY on a live key). At least one field. The old nights go back on the sandbox's availability, the new ones come off; channel.booking.modified carries changes and previous. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `checkIn` | string | no | New arrival, YYYY-MM-DD in the property's timezone; today or later | | `nights` | integer | no | New length of stay, 1–30 | | `rooms` | integer | no | New number of rooms, 1–5 | | `adults` | integer | no | New adults per room | | `guestName` | string | no | The guest renamed, as a channel sometimes does | Sample body: ```json { "nights": 3, "guestName": "Asha Verma-Rao" } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookingId` | integer | yes | The PMS booking id, the one the webhook carries | | `reference` | string | yes | The booking reference, SBX-… — the webhook's booking.reference | | `channelBookingId` | string | yes | The pretend channel-side id | | `otaName` | string | yes | | | `status` | "UPCOMING" · "CANCELLED" | yes | | | `guestName` | string | yes | | | `checkIn` | string | yes | | | `checkOut` | string | yes | | | `nights` | integer | yes | | | `rooms` | integer | yes | | | `roomTypeId` | integer | yes | | | `nightlyRate` | number | yes | Major units, per room per night | | `total` | number | yes | Major units | | `currency` | string | yes | | | `paidByOta` | boolean | yes | | | `oversold` | boolean | yes | true when a night had no sandbox availability left — the booking lands anyway, as an OTA booking would | | `createdAt` | string | yes | | | `webhook` | object | yes | What this call put on the wire for the sandbox's webhook endpoints | | `webhook.eventType` | "channel.booking.created" · "channel.booking.modified" · "channel.booking.cancelled" · "direct.booking.created" · "direct.booking.cancelled" | yes | | | `webhook.queued` | boolean | yes | The event is in the outbox; every active endpoint on the sandbox receives it within seconds | ### GET /bookings Bookings the API created on this property, newest first. Scope `bookings:read`. Scope bookings:read. Only bookings a key of this property created; front-desk and OTA bookings are never listed. Query: - `since`: Created on or after this instant; default the last 7 days - `externalReference`: Only the booking with your reservation id - `limit`: Default 50 Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `since` | string | yes | | | `items` | array of objects | yes | | | `items[].bookingId` | integer | yes | | | `items[].reference` | string | yes | | | `items[].externalReference` | string or null | yes | | | `items[].status` | "UPCOMING" · "INHOUSE" · "COMPLETED" · "CANCELLED" · "NOSHOW" | yes | | | `items[].checkIn` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `items[].checkOut` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `items[].nights` | integer | yes | | | `items[].currency` | string | yes | | | `items[].totalAmount` | string | yes | MAJOR units, two decimals: the whole stay | | `items[].totalPaid` | string | yes | MAJOR units, two decimals: collected so far | | `items[].balanceDue` | string | yes | MAJOR units, two decimals: owed at the hotel | | `items[].guest` | object | yes | | | `items[].guest.name` | string | yes | | | `items[].guest.phone` | string | yes | | | `items[].guest.email` | string or null | yes | | | `items[].rooms` | array of objects | yes | | | `items[].rooms[].bookingRoomId` | integer | yes | | | `items[].rooms[].roomTypeId` | integer | yes | | | `items[].rooms[].ratePlanId` | integer or null | yes | | | `items[].rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `items[].rooms[].adults` | integer | yes | | | `items[].rooms[].children` | integer | yes | | | `items[].rooms[].nightlyRate` | string | yes | MAJOR units, two decimals | | `items[].rooms[].status` | "UPCOMING" · "CHECKEDIN" · "CHECKEDOUT" · "CANCELLED" · "NOSHOW" | yes | | | `items[].inventory` | object | yes | | | `items[].inventory.eventRecorded` | boolean | yes | | | `items[].inventory.channelManager` | boolean | yes | false = this property has no channel manager; nothing is pushed | | `items[].inventory.pushedBy` | "inventory-drain" | yes | | | `items[].replay` | boolean | yes | | | `items[].createdAt` | string | yes | | | `items[].cancelledAt` | string or null | yes | | ### GET /bookings/{bookingId} One booking the API created. Scope `bookings:read`. Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookingId` | integer | yes | | | `reference` | string | yes | | | `externalReference` | string or null | yes | | | `status` | "UPCOMING" · "INHOUSE" · "COMPLETED" · "CANCELLED" · "NOSHOW" | yes | | | `checkIn` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `checkOut` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `nights` | integer | yes | | | `currency` | string | yes | | | `totalAmount` | string | yes | MAJOR units, two decimals: the whole stay | | `totalPaid` | string | yes | MAJOR units, two decimals: collected so far | | `balanceDue` | string | yes | MAJOR units, two decimals: owed at the hotel | | `guest` | object | yes | | | `guest.name` | string | yes | | | `guest.phone` | string | yes | | | `guest.email` | string or null | yes | | | `rooms` | array of objects | yes | | | `rooms[].bookingRoomId` | integer | yes | | | `rooms[].roomTypeId` | integer | yes | | | `rooms[].ratePlanId` | integer or null | yes | | | `rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `rooms[].adults` | integer | yes | | | `rooms[].children` | integer | yes | | | `rooms[].nightlyRate` | string | yes | MAJOR units, two decimals | | `rooms[].status` | "UPCOMING" · "CHECKEDIN" · "CHECKEDOUT" · "CANCELLED" · "NOSHOW" | yes | | | `inventory` | object | yes | | | `inventory.eventRecorded` | boolean | yes | | | `inventory.channelManager` | boolean | yes | false = this property has no channel manager; nothing is pushed | | `inventory.pushedBy` | "inventory-drain" | yes | | | `replay` | boolean | yes | | | `createdAt` | string | yes | | | `cancelledAt` | string or null | yes | | Sample answer (`data`): ```json { "bookingId": 48213, "reference": "SB-7KQ2MX9D", "externalReference": "WEB-2026-000123", "status": "UPCOMING", "checkIn": "2026-12-20", "checkOut": "2026-12-23", "nights": 3, "currency": "INR", "totalAmount": "27000.00", "totalPaid": "9000.00", "balanceDue": "18000.00", "guest": { "name": "Asha Verma", "phone": "+919876543210", "email": "asha@example.com" }, "rooms": [ { "bookingRoomId": 90001, "roomTypeId": 412, "ratePlanId": null, "mealPlan": "CP", "adults": 2, "children": 1, "nightlyRate": "4500.00", "status": "UPCOMING" }, { "bookingRoomId": 90002, "roomTypeId": 412, "ratePlanId": null, "mealPlan": "CP", "adults": 2, "children": 0, "nightlyRate": "4500.00", "status": "UPCOMING" } ], "inventory": { "eventRecorded": true, "channelManager": true, "pushedBy": "inventory-drain" }, "replay": false, "createdAt": "2026-10-20T09:14:03.201Z", "cancelledAt": null } ``` ### POST /bookings Create a booking in the PMS from your own booking engine. Scope `bookings:write`. Scope bookings:write (+ bookings:payments to record a payment). One entry in `rooms` per room. The stay is checked for availability under the property's inventory lock and written with its inventory event in one transaction; the channels update within seconds. A repeated externalReference answers 200 with the same booking (replay: true) while it is this key's and live; another key's reference, or one of your own cancelled bookings, is 409 EXTERNAL_REFERENCE_REUSED (send a new reference after a cancel). 1–90 nights, arrival from today to today + horizonDays, in the property's timezone. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `externalReference` | string | yes | Your own reservation id; unique per property. A retried POST with the same value returns the same booking while it is live and yours; after a cancel, a new stay needs a new reference (409 EXTERNAL_REFERENCE_REUSED otherwise) | | `checkIn` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `checkOut` | string | yes | Exclusive: the checkout day is not a night | | `currency` | string | yes | ISO 4217; must equal the property's (GET /property) | | `guest` | object | yes | Who booked; found or created in the PMS by phone | | `guest.name` | string | yes | Full name as the guest typed it | | `guest.phone` | string | yes | Guest phone, digits with an optional leading + | | `guest.email` | string (email) | no | Guest email, when you have it; we write to it only if the owner switches our confirmation on | | `guest.notes` | string | no | Special requests for the desk; shown in the PMS, never sent anywhere | | `rooms` | array of objects | yes | One entry per ROOM; two rooms of the same type are two entries | | `rooms[].roomTypeId` | integer | yes | ZimmerStack room type id: roomTypes[].id from GET /catalog, never guessed | | `rooms[].ratePlanId` | integer | no | Optional: the plan the guest booked, ratePlans[].id from GET /catalog; must belong to roomTypeId. Decides the meal plan; omitted = room only (EP) | | `rooms[].adults` | integer | yes | Adults in this room; at most the room type's maxAdults | | `rooms[].children` | integer | no | Children in this room; default 0; at most the room type's maxChildren | | `rooms[].nightlyRate` | number or string | yes | The nightly price YOU charged for this room, MAJOR units (e.g. 4500 or "4500.00"), 1 to 21474836, taxes as you sold them | | `payment` | object | no | Omit when nothing was collected; an amount above 0 needs the bookings:payments scope | | `payment.amount` | number or string | yes | What you collected so far, MAJOR units; 0 = nothing collected (pay at hotel); never more than the stay's total | | `payment.method` | "ONLINE" · "CARD" · "UPI" · "NETBANKING" · "CASH" | yes | How you collected it | | `payment.reference` | string | no | Your gateway's payment or transaction id | | `notes` | string | no | Booking-level remarks for the desk (promo code, source page) | Sample body: ```json { "externalReference": "WEB-2026-000123", "checkIn": "2026-12-20", "checkOut": "2026-12-23", "currency": "INR", "guest": { "name": "Asha Verma", "phone": "+919876543210", "email": "asha@example.com", "notes": "Late arrival, after 22:00" }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "adults": 2, "children": 1, "nightlyRate": "4500.00" }, { "roomTypeId": 412, "ratePlanId": 901, "adults": 2, "nightlyRate": "4500.00" } ], "payment": { "amount": "9000.00", "method": "ONLINE", "reference": "pay_QwErTy123" }, "notes": "Promo WINTER10 applied on the website" } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookingId` | integer | yes | | | `reference` | string | yes | | | `externalReference` | string or null | yes | | | `status` | "UPCOMING" · "INHOUSE" · "COMPLETED" · "CANCELLED" · "NOSHOW" | yes | | | `checkIn` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `checkOut` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `nights` | integer | yes | | | `currency` | string | yes | | | `totalAmount` | string | yes | MAJOR units, two decimals: the whole stay | | `totalPaid` | string | yes | MAJOR units, two decimals: collected so far | | `balanceDue` | string | yes | MAJOR units, two decimals: owed at the hotel | | `guest` | object | yes | | | `guest.name` | string | yes | | | `guest.phone` | string | yes | | | `guest.email` | string or null | yes | | | `rooms` | array of objects | yes | | | `rooms[].bookingRoomId` | integer | yes | | | `rooms[].roomTypeId` | integer | yes | | | `rooms[].ratePlanId` | integer or null | yes | | | `rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `rooms[].adults` | integer | yes | | | `rooms[].children` | integer | yes | | | `rooms[].nightlyRate` | string | yes | MAJOR units, two decimals | | `rooms[].status` | "UPCOMING" · "CHECKEDIN" · "CHECKEDOUT" · "CANCELLED" · "NOSHOW" | yes | | | `inventory` | object | yes | | | `inventory.eventRecorded` | boolean | yes | | | `inventory.channelManager` | boolean | yes | false = this property has no channel manager; nothing is pushed | | `inventory.pushedBy` | "inventory-drain" | yes | | | `replay` | boolean | yes | | | `createdAt` | string | yes | | | `cancelledAt` | string or null | yes | | Sample answer (`data`): ```json { "bookingId": 48213, "reference": "SB-7KQ2MX9D", "externalReference": "WEB-2026-000123", "status": "UPCOMING", "checkIn": "2026-12-20", "checkOut": "2026-12-23", "nights": 3, "currency": "INR", "totalAmount": "27000.00", "totalPaid": "9000.00", "balanceDue": "18000.00", "guest": { "name": "Asha Verma", "phone": "+919876543210", "email": "asha@example.com" }, "rooms": [ { "bookingRoomId": 90001, "roomTypeId": 412, "ratePlanId": null, "mealPlan": "CP", "adults": 2, "children": 1, "nightlyRate": "4500.00", "status": "UPCOMING" }, { "bookingRoomId": 90002, "roomTypeId": 412, "ratePlanId": null, "mealPlan": "CP", "adults": 2, "children": 0, "nightlyRate": "4500.00", "status": "UPCOMING" } ], "inventory": { "eventRecorded": true, "channelManager": true, "pushedBy": "inventory-drain" }, "replay": false, "createdAt": "2026-10-20T09:14:03.201Z", "cancelledAt": null } ``` ### POST /bookings/{bookingId}/cancel Cancel a booking the API created; its nights re-open on the channels. Scope `bookings:write`. Scope bookings:write. Idempotent: an already-cancelled booking answers 200 with replay: true. A booking the desk has checked in is 409 BOOKING_NOT_CANCELLABLE. Body: | Field | Type | Required | Meaning | |---|---|---|---| | `reason` | string | no | Why; kept on the booking's activity log | Sample body: ```json { "reason": "Guest cancelled on the website" } ``` Answer (`data`): | Field | Type | Required | Meaning | |---|---|---|---| | `bookingId` | integer | yes | | | `reference` | string | yes | | | `externalReference` | string or null | yes | | | `status` | "UPCOMING" · "INHOUSE" · "COMPLETED" · "CANCELLED" · "NOSHOW" | yes | | | `checkIn` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `checkOut` | string | yes | Hotel-local calendar date, YYYY-MM-DD | | `nights` | integer | yes | | | `currency` | string | yes | | | `totalAmount` | string | yes | MAJOR units, two decimals: the whole stay | | `totalPaid` | string | yes | MAJOR units, two decimals: collected so far | | `balanceDue` | string | yes | MAJOR units, two decimals: owed at the hotel | | `guest` | object | yes | | | `guest.name` | string | yes | | | `guest.phone` | string | yes | | | `guest.email` | string or null | yes | | | `rooms` | array of objects | yes | | | `rooms[].bookingRoomId` | integer | yes | | | `rooms[].roomTypeId` | integer | yes | | | `rooms[].ratePlanId` | integer or null | yes | | | `rooms[].mealPlan` | "EP" · "CP" · "MAP" · "AP" | yes | | | `rooms[].adults` | integer | yes | | | `rooms[].children` | integer | yes | | | `rooms[].nightlyRate` | string | yes | MAJOR units, two decimals | | `rooms[].status` | "UPCOMING" · "CHECKEDIN" · "CHECKEDOUT" · "CANCELLED" · "NOSHOW" | yes | | | `inventory` | object | yes | | | `inventory.eventRecorded` | boolean | yes | | | `inventory.channelManager` | boolean | yes | false = this property has no channel manager; nothing is pushed | | `inventory.pushedBy` | "inventory-drain" | yes | | | `replay` | boolean | yes | | | `createdAt` | string | yes | | | `cancelledAt` | string or null | yes | | ## What a write answers A write is accepted, not blocked: Your 202 means the cells are in our record. Pushing them to the channel manager is paced by its budget — ten rate/restriction reads a minute for the whole account and a per-property write budget — so a full calendar takes minutes, never seconds, and is never lost. We coalesce your cells into the fewest channel-manager calls, drop what did not change, pace every call, stop before the channel manager's last token, and back off on its Retry-After — you never have to think about its limits, only about ours. ```json { "batchId": "7f1d2c4e-5a6b-4c8d-9e0f-112233445566", "resource": "rates", "requestedCells": 151, "acceptedCells": 43, "noopCells": 108, "rejected": [], "pushedBy": "ari-projector", "poll": "/api/v1/connect-api/v1/batches/7f1d2c4e-5a6b-4c8d-9e0f-112233445566" } ``` The batch, polled: ```json { "batchId": "7f1d2c4e-5a6b-4c8d-9e0f-112233445566", "resource": "rates", "createdAt": "2026-10-12T09:14:03.201Z", "requestedCells": 151, "acceptedCells": 43, "noopCells": 108, "rejected": [], "status": "pending", "pendingCells": 12, "parkedCells": 0, "lastError": null } ``` ## Limits Window: 60 s sliding, shared by every API machine; counters are exact, not per machine. | `data.scope` | Per minute | Counts | |---|---|---| | `ip` | 240 | every request from one address, checked before the key is read | | `ip-auth` | 20 | 401 answers to one address; after that the address is refused before any lookup | | `requests` | 120 | every request on one key | | `writes` | 30 | PUT requests on one key | | `property` | 300 | every request on all of a property's keys together (five keys are not five budgets) | | `property-writes` | 60 | PUT requests on all of a property's keys together | | `cells` | 20,000 | cells a property's writes name after range expansion, charged before anything is read or written | | `bookings` | 20 | POST /bookings on one key | | `property-bookings` | 40 | POST /bookings on all of a property's keys together | | `property-bookings-day` | 500 | POST /bookings per property per ROLLING 24 HOURS (not per minute); the owner can raise it per property | | `company` | 1,200 | every request on one company key, across all its hotels (each hotel keeps its own key and property budgets too) | | `global` | 3,000 | every request on the Connect API, all keys and addresses | One request: at most 1,000 updates, 5,000 cells and 1,048,576 bytes. Writes reach 365 days ahead. Headers: - `RateLimit-Policy`: on every answer, one quoted policy per key scope — "key";q=120;w=60, "key-writes";q=30;w=60 - `RateLimit`: on every answer, what is left and when it refills — "key";r=117;t=42, "key-writes";r=29;t=42 - `Retry-After`: on every 429, whole seconds to wait; the body's data.scope says which budget refused On a refusal: 429 RATE_LIMITED. Wait Retry-After, then resend the same request. Never retry in a tight loop; never retry any other 4xx. How to pace: - Batch: one PUT per resource carrying ranges (dateFrom..dateTo, optional days) — a 365-night calendar for three plans is a handful of updates, not a thousand - Send on change, not on a timer: unchanged cells are dropped and cost nothing, but they still spend your request budget - Read RateLimit on every answer and slow down when r approaches 0, instead of waiting for a 429 - Reuse x-idempotency-key on a retry so a timed-out request can never land twice - Poll GET /batches/{batchId} and GET /sync no more than every 15 s; the push to the channels is asynchronous and bounded by the channel manager's own budget ### Budgets over an hour and a day, structure limits, the price band, standing On top of the per-minute budgets, every property has budgets over an hour and a day, hard limits on its structure, and a standing ZimmerStack can change. They exist because every changed cell is forwarded by the channel manager to every connected channel: an integration that re-sends, flaps or loops is the hotel's and the channels' problem within a minute. GET /property carries this property's own figures (limits), what it has used (usage) and where it stands (shield). A budget counts CHANGED cells: cells whose value differs from our record. Re-sending a calendar we already hold costs nothing here. So send on change, in ranges. One full calendar of a property is (2 × its rate plans + its room types) × 365 nights: a price and a stay-rule cell for every plan night, an availability cell for every room-type night. The figures in the table are the least any property gets; a larger one gets whole calendars. An hour: 2 full calendars; a day: 6. A software vendor's hotels together: 150,000 a day plus 15,000 for each hotel. Every key on a property spends the same budget: a second key, or a company key beside a hotel key, is not a second budget. `GET /property` answers a hotel's exact `limits` and `usage`. | `data.scope` | Window | At least | Counts | |---|---|---|---| | `cells-hour` | one clock hour (UTC) | 10,000 | changed cells, all of a property's keys together. At least this many; a larger property gets two of its own full calendars an hour | | `cells-day` | rolling 24 hours | 30,000 | changed cells, all of a property's keys together. At least this many; a larger property gets six of its own full calendars a day | | `vendor-cells-day` | rolling 24 hours | 150,000 | a software vendor's changed cells across all its hotels (company keys and keys it minted). At least this many, plus 15,000 for each hotel it serves; a sandbox is never counted here | | `structure-creates` | 60 s sliding | 20 | new room types and rate plans per property; also the most one request may create (TOO_MANY_NEW_ENTITIES) | | `structure-creates-day` | rolling 24 hours | 300 | new room types and rate plans per property | | `structure-edits-day` | rolling 24 hours | 300 | changed room types and rate plans per property | | `structure-deletes-day` | rolling 24 hours | 60 | deleted room types and rate plans per property | | `vendor-structure-creates-day` | rolling 24 hours | 500 | a software vendor's new room types and rate plans across all its hotels | | `vendor-remote-properties-day` | rolling 24 hours | 10 | hotels a software vendor puts on the channel manager for the first time | | `modifier-changes-day` | rolling 24 hours | 6 | changes to a channel's price modifier per property (PUT /channels/{channelId}/modifier); steps the channel already holds are not counted | | `rate-resends-day` | rolling 24 hours | 3 | times a property's prices are sent to the channels again (POST /rates/resend) | On a refusal: 429 RATE_LIMITED with data.scope naming the budget and Retry-After in whole seconds: to the next clock hour for cells-hour, until enough of the day has aged out for a rolling day. Nothing was written. Wait, then send what still needs to change. Structure: a hotel holds at most 18 room types and 180 rate plans by default (`GET /property` carries the property's own). 409 CATALOG_LIMIT_REACHED (details.limit, details.current, details.requested). Delete what is unused, or ask ZimmerStack support. The safety lane: A hotel must not oversell because its integration ran out of budget or was paused. A write that only CLOSES inventory (a lower availability count or 0, or stopSell / closedToArrival / closedToDeparture switched on, and nothing else in the request) is still accepted in both cases, against its own hourly allowance (at least 500 cells); its 202 carries lane: true. A write that opens inventory or changes a price waits. The price band: PUT /rates takes prices in MAJOR units; reads answer in MINOR units. A price below a tenth or above ten times its plan's standing price (the plan's defaultRate, or its room type's base rate) is not taken on trust: the whole request is 422 RATE_OUT_OF_BAND and nothing is written. A plan with no standing price is never judged. If the price is meant, move the plan's standing price first (PUT /catalog/rate-plans defaultRate): the band moves with it. ZimmerStack support can set a property to warn only (the 202 then carries priceWarnings) or switch its band off; the hotel's owner asks for it. Standing: - `CLEAR`: Nothing held against the integration. - `WATCH`: Something notable happened (a budget was used up). Nothing is refused. - `PAUSED`: Only writes that close inventory are accepted (the safety lane); anything else is 429 RATE_LIMITED with data.scope shield-pause and a Retry-After that ends with the pause. Set automatically for a while when the channel manager refuses the integration's values or it uses up a budget on two of three days (15 minutes, then 1 hour, 6 hours, a day), or by ZimmerStack support until released. - `SUSPENDED`: Every write is 403 WRITES_SUSPENDED until ZimmerStack support releases it. - Frozen: 503 WRITES_FROZEN with Retry-After: ZimmerStack has paused every integration's writes at once. Rare, short, and never your integration alone. - Never refused: Reads, GET /channel-bookings, webhooks and POST /bookings are never refused by any of this: a guest's reservation and its news always travel. Values the channel manager refuses: A rate or restriction value the channel manager itself refuses is held, not re-sent: GET /sync counts it (rates.parkedCells), its batch reads failed with the reason, and the property's other cells keep landing. Send a corrected value for those nights. ## Error codes Branch on `data.code`. Every code the API can answer: `API_KEY_INVALID`, `API_KEY_REVOKED`, `API_KEY_EXPIRED`, `CONNECT_API_NOT_CONFIGURED`, `IP_NOT_ALLOWED`, `SCOPE_MISSING`, `PROPERTY_UNAVAILABLE`, `CHANNEL_MANAGER_DISABLED`, `PMS_NOT_AVAILABLE`, `VALIDATION`, `RANGE_INVALID`, `HORIZON`, `TOO_MANY_UPDATES`, `TOO_MANY_CELLS`, `UNKNOWN_ROOM_TYPE`, `UNKNOWN_RATE_PLAN`, `CURRENCY_MISMATCH`, `RATE_LIMITED`, `NOTHING_ACCEPTED`, `BATCH_NOT_FOUND`, `IDEMPOTENCY_KEY_INVALID`, `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_FLIGHT`, `STAY_INVALID`, `UNKNOWN_ROOM_TYPE_FOR_PLAN`, `OCCUPANCY_EXCEEDED`, `NO_AVAILABILITY`, `EXTERNAL_REFERENCE_REUSED`, `PAYMENT_NOT_ALLOWED`, `PAYMENT_EXCEEDS_TOTAL`, `BOOKING_NOT_FOUND`, `BOOKING_NOT_CANCELLABLE`, `MODULE_NOT_ENTITLED`, `SANDBOX_ONLY`, `ROOM_TYPE_NOT_FOUND`, `RATE_PLAN_NOT_FOUND`, `CATALOG_CONFLICT`, `CATALOG_BUSY`, `CHANNEL_MANAGER_ERROR`, `PROPERTY_REQUIRED`, `PROPERTY_NOT_FOUND`, `ARI_NOT_AUTHORITATIVE`, `ROUTE_NOT_FOUND`, `PAYLOAD_TOO_LARGE`, `AUTH_BACKEND_UNAVAILABLE`, `BOOKING_NOT_MODIFIABLE`, `SANDBOX_NOT_FOUND`, `SANDBOX_INCOMPLETE`, `WRITES_FROZEN`, `WRITES_SUSPENDED`, `SHIELD_UNAVAILABLE`, `CATALOG_LIMIT_REACHED`, `TOO_MANY_NEW_ENTITIES`, `RATE_OUT_OF_BAND`, `CHANNEL_NOT_FOUND`, `CHANNEL_SHARED`, `MODIFIER_OUT_OF_BAND`. | Code | Status | Sample message | |---|---|---| | `API_KEY_INVALID` | 401 | Unauthorized | | `API_KEY_REVOKED` | 401 | Unauthorized | | `IP_NOT_ALLOWED` | 403 | This API key may not be used from this address. The property owner restricts it to an allowlist. | | `SCOPE_MISSING` | 403 | This API key does not have the bookings:write scope. The property owner grants scopes when creating or editing a key. | | `PROPERTY_UNAVAILABLE` | 409 | This property is not available to the API any more. Contact the property owner. | | `CHANNEL_MANAGER_DISABLED` | 409 | This property's channel manager is switched off, so writes would not reach any channel. Contact the property owner. | | `PMS_NOT_AVAILABLE` | 409 | This property runs the channel manager only; there is no PMS to put a booking in. | | `VALIDATION` | 400 | updates[0].available: Expected number, received string | | `HORIZON` | 400 | updates[0]: 2028-01-01 is beyond the horizon (last writable night is 2027-10-12, today + 365 days) | | `TOO_MANY_CELLS` | 400 | a request may name at most 5000 cells (entity × night); split the calendar into several requests | | `UNKNOWN_RATE_PLAN` | 400 | rate plan(s) 77 do not belong to this property (see GET /catalog) | | `CURRENCY_MISMATCH` | 400 | rates must be sent in INR (got EUR) | | `RATE_LIMITED` | 429 | Too many requests on this API key. Slow down and retry after the Retry-After interval. | | `NOTHING_ACCEPTED` | 422 | exceptions are switched off for this property — move the base rate instead | | `BATCH_NOT_FOUND` | 404 | Batch not found. | | `STAY_INVALID` | 400 | checkIn 2026-10-01 is in the past (today at the property is 2026-10-20) | | `OCCUPANCY_EXCEEDED` | 400 | rooms[0]: Deluxe takes at most 3 adults (got 4) | | `NO_AVAILABILITY` | 409 | room type 412 has 0 left on 2026-12-21; 1 requested | | `PAYMENT_NOT_ALLOWED` | 403 | This API key may not record payments. The property owner grants the bookings:payments scope. | | `PAYMENT_EXCEEDS_TOTAL` | 400 | payment.amount 30000.00 exceeds the stay total 27000.00 | | `BOOKING_NOT_FOUND` | 404 | Booking not found. | | `PROPERTY_REQUIRED` | 400 | This is a company key: name the hotel in the X-ZS-Property header, with its id from GET /properties. | | `PROPERTY_NOT_FOUND` | 404 | No property with this id that this key may act on (see GET /properties). | | `ARI_NOT_AUTHORITATIVE` | 409 | This property's local rates and availability are not the channels' source of truth yet, so API writes would never be pushed. Contact ZimmerStack support. | | `ROOM_TYPE_NOT_FOUND` | 404 | That room type doesn't exist. | | `RATE_PLAN_NOT_FOUND` | 404 | That rate plan doesn't exist. | | `CATALOG_CONFLICT` | 409 | A room type with this name already exists. | | `CHANNEL_MANAGER_ERROR` | 502 | The channel manager refused the delete. Nothing changed here; try again in a moment. | | `BOOKING_NOT_CANCELLABLE` | 409 | Booking already checked in. Ask the hotel to handle it at the desk. | | `BOOKING_NOT_MODIFIABLE` | 409 | A cancelled booking cannot be modified from the sandbox. | | `CATALOG_BUSY` | 409 | Another room-type or rate-plan write for this property is still running. Retry in a few seconds. | | `ROUTE_NOT_FOUND` | 404 | No GET /api/v1/connect-api/v1/nope in the Connect API; the contract lists every route. | | `PAYLOAD_TOO_LARGE` | 413 | The request body is larger than the API accepts. Split the updates array across requests. | | `API_KEY_EXPIRED` | 401 | Unauthorized | | `SANDBOX_ONLY` | 403 | The sandbox routes answer only to a test key (zsk_test_…) on a sandbox property. This key is a live key. | | `MODULE_NOT_ENTITLED` | 402 | This property's plan does not include the PMS. | | `WRITES_FROZEN` | 503 | ZimmerStack has paused every write to the channel manager for now. Nothing was written. Retry after the Retry-After interval; reads and bookings are not affected. | | `WRITES_SUSPENDED` | 403 | ZimmerStack has suspended writes for this integration: it kept sending after repeated notices. Reads and bookings still work. Contact ZimmerStack support to have it released. | | `SHIELD_UNAVAILABLE` | 503 | The write could not be checked against this property's budgets right now. Nothing was written. Retry after the Retry-After interval. | | `CATALOG_LIMIT_REACHED` | 409 | This property holds 298 rate plans and may hold 300; this request would add 6. Delete what is unused, or ask ZimmerStack support to raise the limit. | | `TOO_MANY_NEW_ENTITIES` | 400 | This request would create 34 new room types or rate plans; one request may create at most 20. Entities that already exist do not count. Split the new ones across requests. | | `RATE_OUT_OF_BAND` | 422 | rate plan 901 on 2026-12-01: 45 INR is below the band around this plan's standing price 4500 INR (lowest accepted 450) (and 29 more cells). Rates are sent in major units (4500, not 450000). If the price is meant, change the plan's standing price first (PUT /catalog/rate-plans defaultRate), or ask ZimmerStack support to lift the band for this property. | | `CHANNEL_NOT_FOUND` | 404 | No connected channel with this id on this property. GET /channels lists them. | | `CHANNEL_SHARED` | 409 | This connection serves more than one property, so its modifier would move another hotel's prices too. It is set by the hotels' owner in ZimmerStack, not through this API. Nothing was changed. | | `MODIFIER_OUT_OF_BAND` | 422 | These steps would change what the channel is sent by +180%; a channel's modifier must stay between 50% lower and 100% higher. Nothing was changed. | | `IDEMPOTENCY_KEY_REUSED` | 409 | This idempotency key was already used with a different request body. | ## Webhooks Every OTA booking, change and cancellation is posted, signed, to the HTTPS endpoint the hotel registers (Admin → Developers → Webhooks, or the partner portal for a company endpoint). Full contract: https://api.zimmerstack.com/api/v1/public/webhooks/contract - `channel.booking.created`: an OTA booking arrives through the channel manager - `channel.booking.modified`: the OTA sends a revision (dates, rooms, amounts, guest) - `channel.booking.cancelled`: the OTA cancels; for a booking we never received (one made before the hotel moved here) it arrives with no created before it - `direct.booking.created`: a guest books on the hotel's own website through the ZimmerStack booking engine (nightly or hourly); a family of its own, see Bookings from the hotel's own website - `direct.booking.cancelled`: the guest cancels on the booking page, or the hotel cancels or deletes the booking in ZimmerStack - `zimmerstack.ping`: only ever a test, from the UI or on registration - `channel.sync.alert` and `channel.sync.recovered`: a problem the channel manager reported for the property, and its recovery; they carry `data.sync` instead of `data.booking` Website bookings (`direct.booking.*`) are a family of their own beside the OTA one, with the same booking object and envelope. See the guide on the hotel's own website bookings below. A sample of each: ```json { "id": "evt_9b1d7c52-3e0a-4f6b-8a14-6c2e5d0f7a31", "type": "direct.booking.created", "apiVersion": "2026-09-01", "occurredAt": "2026-10-30T12:00:00.000Z", "mode": "live", "property": { "id": 61, "name": "The Lantern House", "currency": "INR", "timezone": "Asia/Kolkata" }, "data": { "booking": { "id": 100001, "reference": "TEST-WEB-4H7P9D", "status": "CONFIRMED", "stayStatus": "UPCOMING", "channel": { "otaName": "Website", "otaReservationCode": "TEST-WEB-4H7P9D", "source": "DIRECT_WEB", "sourceGroup": "DIRECT" }, "stay": { "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false }, "guest": { "fullName": "Asha Verma", "firstName": "Asha", "lastName": "Verma", "phone": "+919876500000", "email": "asha.verma@example.com", "country": "IN", "language": "en" }, "guestNotes": null, "occupancy": { "adults": 2, "children": 0 }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "roomTypeName": "Deluxe Sea View", "mealPlan": "CP", "adults": 2, "children": 0, "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false, "ratePerNight": 2700, "amount": 5400, "status": "UPCOMING" } ], "amounts": { "currency": "INR", "total": 5400, "paid": 1080, "balanceDue": 4320, "paymentCollect": "property" }, "finance": null, "cancellation": null, "createdAt": "2026-10-30T12:00:00.000Z", "updatedAt": "2026-10-30T12:00:00.000Z" } }, "changes": null, "previous": null } ``` ```json { "id": "evt_2c7e4a90-5d1b-4b83-9f26-1a8d3e6b0c54", "type": "direct.booking.cancelled", "apiVersion": "2026-09-01", "occurredAt": "2026-10-30T13:00:00.000Z", "mode": "live", "property": { "id": 61, "name": "The Lantern House", "currency": "INR", "timezone": "Asia/Kolkata" }, "data": { "booking": { "id": 100001, "reference": "TEST-WEB-4H7P9D", "status": "CANCELLED", "stayStatus": "CANCELLED", "channel": { "otaName": "Website", "otaReservationCode": "TEST-WEB-4H7P9D", "source": "DIRECT_WEB", "sourceGroup": "DIRECT" }, "stay": { "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false }, "guest": { "fullName": "Asha Verma", "firstName": "Asha", "lastName": "Verma", "phone": "+919876500000", "email": "asha.verma@example.com", "country": "IN", "language": "en" }, "guestNotes": null, "occupancy": { "adults": 2, "children": 0 }, "rooms": [ { "roomTypeId": 412, "ratePlanId": 901, "roomTypeName": "Deluxe Sea View", "mealPlan": "CP", "adults": 2, "children": 0, "checkIn": "2026-11-13", "checkOut": "2026-11-15", "nights": 2, "dayUse": false, "ratePerNight": 2700, "amount": 5400, "status": "CANCELLED" } ], "amounts": { "currency": "INR", "total": 5400, "paid": 1080, "balanceDue": 4320, "paymentCollect": "property" }, "finance": null, "cancellation": { "at": "2026-10-30T13:00:00.000Z", "reason": "Cancelled by the guest" }, "createdAt": "2026-10-30T12:00:00.000Z", "updatedAt": "2026-10-30T13:00:00.000Z" } }, "changes": null, "previous": null } ``` Envelope: ```json { "id": "evt_5d3f0c4a-6b1e-4a7e-9c1b-2f0e8d1a9b77", "type": "channel.booking.created", "apiVersion": "2026-09-01", "occurredAt": "2026-09-12T08:14:03.201Z", "mode": "live", "property": { "id": 61, "name": "Sea Breeze Apartments", "currency": "INR", "timezone": "Asia/Kolkata" }, "data": { "booking": { "…": "the normalised booking: reference, status, stay, rooms, guest, amounts, channel" } }, "changes": null, "previous": null } ``` Deliveries follow the Standard Webhooks spec: HMAC-SHA256 over `id.timestamp.body` with the endpoint's secret. Verify with a constant-time compare and refuse timestamps older than five minutes. ```js import { createHmac, timingSafeEqual } from "node:crypto"; // Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature headers. export function verify(headers, rawBody, secret) { const id = headers["webhook-id"]; const ts = headers["webhook-timestamp"]; const given = String(headers["webhook-signature"] ?? ""); if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // 5-minute window const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64"); return given.split(" ").some((sig) => { const [, value] = sig.split(","); return value && value.length === expected.length && timingSafeEqual(Buffer.from(value), Buffer.from(expected)); }); } ``` ### When your server is down - **Answer fast.** Answer 2xx within 10 seconds and do the work afterwards. The endpoint is HTTPS on a public host; a redirect is not followed. - **Retries.** Anything other than 2xx, a timeout or a connection error is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h and 12 h (about a day in all, ±20%), then the delivery is marked failed. A 429 or 503 with Retry-After is retried no sooner than it says (at most an hour). A 410 Gone pauses the endpoint. - **Who is told.** We e-mail whoever registered the endpoint after an hour and after a day of failures. After 72 hours with no successful delivery the endpoint is suspended. - **Planned downtime.** Pause the endpoint first. A pause holds every event (for up to 90 days) and sends them oldest first when you resume. A suspension holds nothing: resume, then Recover since replays the gap, up to 90 days back. One delivery can be sent again from the log. - **Order.** Deliveries are at-least-once and usually in order, but a retry can arrive after a newer event. Ignore an event id you have already processed; for one booking, the event with the later occurredAt wins. - **Nothing is lost for good.** GET /channel-bookings lists every OTA booking changed since a time you choose, with no limit on how far back, in the webhook's own shape, cancellations included. GET /direct-bookings does the same for the bookings made on the hotel's own website. Each gives a booking's latest version, not the history of a change (changes and previous). ### The money on an OTA booking Every OTA booking carries amounts (the total the hotel's books hold) and finance (where that money comes from and what the OTA keeps). Read finance.amountBasis first: it says whether amounts.total is what the guest paid or what the OTA owes the hotel. finance is null when the OTA sent nothing to work it out from. - `finance.amountBasis`: GROSS_TOTAL: amounts.total is what the guest paid. NET_PAYOUT: amounts.total is what the OTA owes the hotel after its commission. GROSS_EXCL_TAX and NET_EXCL_TAX are the same two before taxes. UNKNOWN: the OTA sent nothing to tell. - `finance.grossAmount`: What the guest paid for the whole booking, with the hotel's taxes. Null when the OTA does not send it. - `finance.commissionAmount`: The OTA's commission for the whole booking, without any tax the OTA charges on it. Null when the OTA does not send it. - `finance.taxAmount`: The taxes the OTA listed on the booking. Null when it listed none. - `finance.netPayoutAmount`: grossAmount minus commissionAmount: what the OTA owes the hotel before its own deductions (a tax on its commission, TCS, TDS). It is not the amount that reaches the bank; the OTA's statement is. - **MakeMyTrip and Goibibo.** When the channel is connected, the hotel chooses what the booking total is: Total Amount (our default) or Payout Amount. The choice changes amounts.total only: what the guest paid under Total Amount (amountBasis GROSS_TOTAL), the payout under Payout Amount (NET_PAYOUT). The finance block means the same under both, grossAmount and commissionAmount included. The commission is worked out on the price before GST. When MakeMyTrip sends no GST line for the hotel, grossAmount is the price before GST and taxAmount is null. MakeMyTrip then deducts 18% GST on its commission, and TCS and TDS (0.5% and 0.1% of the price before GST on the bookings we checked), before it pays. - **Agoda.** The booking carries only Agoda's net amount: what Agoda pays the hotel, taxes included under Agoda's usual tax setting (Inclusive). amounts.total and netPayoutAmount are that amount, amountBasis is NET_PAYOUT, and grossAmount and commissionAmount are null. The guest's price and Agoda's commission are on Agoda's own statement. - **Booking.com.** Always what the guest paid, taxes included: amounts.total and grossAmount are the same, commissionAmount is Booking.com's, netPayoutAmount is the difference. - **Any other OTA.** Read amountBasis: each OTA states its basis differently, and finance says which one this booking used. A MakeMyTrip booking: a ₹4,000 room, 5% GST, 20% commission: - grossAmount: 4,200.00 (4,000 + 200 GST) - commissionAmount: 800.00 (20% of 4,000) - taxAmount: 200.00 - netPayoutAmount: 3,400.00 (4,200 − 800) - amounts.total: 4,200.00 with Total Amount · 3,400.00 with Payout Amount - Reaches the bank: about 3,232.00: 3,400 − 144 (18% GST on the commission) − 20 (TCS) − 4 (TDS) ## Guide: bookings from the hotel's own website You build or run a hotel's PMS, and the hotel keeps it (it is not the ZimmerStack PMS). The hotel uses ZimmerStack's channel manager to sell on the OTAs and its booking engine to sell on its own website. A guest who books on that website never passes through an OTA, so without this your PMS would not hear of the booking, and its next push of room counts would put the room back on sale. Website bookings only: the nightly and the hourly bookings of ZimmerStack's booking engine. A booking made at the front desk, or created by a key with POST /bookings, is not in this family: your own system made it, or the hotel's staff did. - **What they are.** A hotel that sells on its own website through the ZimmerStack booking engine takes bookings no OTA sent. They reach a PMS under their own names: the webhooks direct.booking.created and direct.booking.cancelled, and GET /direct-bookings for the pull. The booking object is the one channel.booking.* carries, so one parser serves both families. - **Tell them apart.** channel.source is DIRECT_WEB, channel.sourceGroup is DIRECT and channel.otaName is "Website". finance is null (no OTA, no commission); amounts.paymentCollect is "property"; amounts.paid is what the guest paid online, amounts.balanceDue what the desk collects. - **Subscribe.** An endpoint receives them only when it lists the two event types. An endpoint registered before they existed receives none until its owner ticks them. - **Apply them first.** A website booking takes one room off the count the channels hold, at once. A PMS that pushes absolute room counts must apply the booking to its own calendar BEFORE its next PUT /availability, or that push puts the sold room back on sale. Read GET /direct-bookings before a full push to catch anything a webhook has not delivered yet. Never push a count that was worked out before the website bookings were applied. - **Events.** created: a nightly or an hourly booking the guest confirmed. cancelled: the guest cancelled on the booking page, or the hotel cancelled or deleted the booking in ZimmerStack; cancellation.reason says which. There is no modified event: the booking engine never changes a booking's dates. - **What sends no event.** What the hotel changes on a website booking in ZimmerStack afterwards (other dates, one room of several cancelled, a no-show) sends no event. GET /direct-bookings lists that booking again, because since is on its last change: read it on a slow schedule too (once an hour is plenty), not only before a push. A cancelled event can also arrive for a booking whose created your endpoint never received (it ticked the types later): treat an unknown booking id as new and read it with GET /direct-bookings/{bookingId}. - **The pull.** GET /direct-bookings takes the same since, status, limit and cursor as GET /channel-bookings and pages the same way. Scope direct-bookings:read, granted separately from channel-bookings:read. A booking deleted in ZimmerStack stays listed, as CANCELLED. The key needs `direct-bookings:read`, a scope of its own: `403 SCOPE_MISSING` names it; ask the owner, do not look for another route. - **Not these.** OTA bookings (GET /channel-bookings), front-desk bookings and bookings a key created (GET /bookings) are never listed here. - **Cancelling.** A website booking is cancelled by the guest on the booking page or by the hotel in ZimmerStack. There is no cancel by API yet: do not build a button that calls `POST /bookings/{bookingId}/cancel` on one (a key reads and cancels only the bookings it created). - **Sandbox.** POST /sandbox/bookings with otaName "Website" simulates one and sends the real direct.booking.created; its cancel sends direct.booking.cancelled. Its modify is 409 BOOKING_NOT_MODIFIABLE. An OTA booking and a website booking, side by side: | Field | OTA booking | Website booking | |---|---|---| | `Event types` | channel.booking.created · modified · cancelled | direct.booking.created · cancelled | | `channel.otaName` | The OTA: "Booking.com", "MakeMyTrip", … | "Website" | | `channel.otaReservationCode` | The OTA's reservation code | ZimmerStack's own booking reference | | `channel.source · channel.sourceGroup` | CHANNEL_MANAGER · INDIRECT | DIRECT_WEB · DIRECT | | `finance` | The OTA's money block (commission, payout), or null | null: no OTA, no commission | | `amounts.paymentCollect` | ota, property or unknown | property: the money is the hotel's, not an OTA's | | `amounts.paid` | The amount recorded as paid so far | What the guest paid online; amounts.balanceDue is what the desk collects | | `changes · previous` | Set on a modified event | Always null: there is no modified event | | `The pull` | GET /channel-bookings, scope channel-bookings:read | GET /direct-bookings, scope direct-bookings:read | How to subscribe: 1. **Register the endpoint.** As for any booking: Admin → Developers → Webhooks, Channels → Integrations, or the partner portal's Developers section for a company endpoint. 2. **Tick the two types.** direct.booking.created and direct.booking.cancelled. An endpoint receives these only when it lists the two types. 3. **An older endpoint needs its owner's tick.** An endpoint registered before these events existed receives none of them until its owner ticks them. Nothing you built before changes. 4. **Allow the read.** The key that reads them holds the scope direct-bookings:read. It is a scope of its own, in the channel-manager family: a software vendor's company key may hold it, and a key that holds channel-bookings:read does not read website guests unasked. A worked example: your PMS holds 5 Deluxe rooms: - 10:00: Your PMS holds 5 Deluxe rooms for 13 November. You pushed that count, so the channels hold 5. - 10:20: A guest books one Deluxe room for that night on the hotel's website. The channels hold 4 at once; our record says 4. - 10:21: direct.booking.created reaches your endpoint. If you do nothing, your PMS still shows 5. - 10:30: Your PMS pushes its full calendar with PUT /availability, and the number for that night is 5, because it never heard of the booking. The channels hold 5 again: the room the guest took is on sale, and an OTA can sell it a second time. - Instead: Apply the booking to your own calendar first. Your PMS then holds 4, and the push says 4. Two safeguards, both yours to keep. Apply direct.booking.created to your calendar before anything else the event triggers, and give a cancellation back (direct.booking.cancelled). And before a full push, read GET /direct-bookings since the last time you read it: it catches any booking a webhook has not delivered yet. ZimmerStack has no guard on the count: it does not refuse a push that is higher than what the website has sold. The answer has since, items, more and nextCursor, as GET /channel-bookings has, and each item is the booking object the webhook carries. Page while more is true, passing nextCursor as cursor. On the first read pass as since the date of the oldest booking your PMS needs to know of; after that, the time of the last change you applied. GET /direct-bookings/{bookingId} reads one: 404 BOOKING_NOT_FOUND for a booking that is not this property's or was not made on its website. Cancellations: - **Who can cancel.** The guest, on the booking page, or the hotel, by cancelling or deleting the booking in ZimmerStack. cancellation.reason is "Cancelled by the guest" or "Cancelled by the hotel". - **What your PMS does.** Give the nights back in your own calendar, and keep the booking as cancelled. The room is on sale again on the channels; your next push should say so. - **A deleted booking.** A booking the hotel deleted in ZimmerStack stays listed by GET /direct-bookings, as CANCELLED, with every room. - **Not by your PMS.** Your PMS cannot cancel a website booking through the API yet. A guest who asks you to cancel is sent to the booking page, or the hotel cancels it in ZimmerStack. Try it on the sandbox: 1. **Register a sandbox endpoint.** On a sandbox, with a test key that holds the channel-manager scopes (the Sandbox page explains how to get one), register a webhook endpoint and tick the two direct types. 2. **Simulate a website booking.** POST /sandbox/bookings with "otaName": "Website"; the other fields are as for an OTA booking. The sandbox's availability goes down by the rooms booked, and your endpoint receives the real direct.booking.created, signed, with mode "test". paidByOta: true means the guest paid online, in full. 3. **Read it back, then cancel it.** GET /direct-bookings lists it. POST /sandbox/bookings/{bookingId}/cancel gives the rooms back and your endpoint receives direct.booking.cancelled. 4. **Know what it refuses.** POST /sandbox/bookings/{bookingId}/modify on a website booking is 409 BOOKING_NOT_MODIFIABLE: there is no modified event, because the real booking engine never changes a booking's dates. What is not there yet: - **No modified event.** The booking engine never changes a booking's dates, so there is no direct.booking.modified. - **No cancel by API.** Your PMS cannot cancel a website booking through the API yet; cancellations come from the guest's booking page or from the hotel in ZimmerStack. - **No guard on the count.** ZimmerStack does not stop a push that puts the sold room back on sale. Applying the booking first is your PMS's job. - **Not the other direction.** Bookings your own booking engine hands to the ZimmerStack PMS are a different thing: POST /bookings, on the Bookings page. **website.ts**: apply a website booking from the webhook, and read GET /direct-bookings before a push of room counts. Checked against this contract on every change to the site. ```ts /** * Bookings guests make on the hotel's own website, in your own PMS (the direct.booking.* family). Runs on your * server, on top of zimmerstack.ts. Two jobs: * * 1. onWebhookEvent: your webhook route calls it with an event whose signature you have already checked * (the Webhooks page has the check). A website booking is put in your own calendar. * 2. pushRoomCounts: your PMS's push of absolute room counts. It reads GET /direct-bookings first, so every * website booking is in your calendar before the counts are worked out. Without that, the push would put * the room the guest took back on sale. * * The key needs the scope direct-bookings:read (and ari:write to push). The endpoint must list the two types * direct.booking.created and direct.booking.cancelled; an endpoint registered earlier hears neither until its * owner ticks them. */ import { zs } from "./zimmerstack"; /** The booking object. It is the one OTA bookings use; only the fields this file reads are named here. */ export interface WebsiteBooking { id: number; reference: string; status: "CONFIRMED" | "CANCELLED"; /** Website bookings: otaName "Website", source "DIRECT_WEB", sourceGroup "DIRECT". */ channel: { otaName: string; otaReservationCode: string; source: string; sourceGroup: string }; stay: { checkIn: string; checkOut: string; nights: number; dayUse: boolean }; /** One entry per room. */ rooms: Array<{ roomTypeId: number; ratePlanId: number | null; checkIn: string; checkOut: string; status: string }>; /** Every change of the booking, created or cancelled, moves this forward. */ updatedAt: string; } /** A verified delivery. `type` is a string: a newer API may add events. */ export interface WebhookEvent { id: string; type: string; data: { booking?: WebsiteBooking }; } /** Yours to write: your own PMS. */ export interface MyCalendar { /** * Store the booking under its `id` with its status, and count its rooms against your own availability: a * CONFIRMED booking takes them, a CANCELLED one gives them back. Applying the same booking twice, or an * older version after a newer one, must change nothing: key it on `id` and ignore an older `updatedAt`. */ setWebsiteBooking(booking: WebsiteBooking): Promise; /** The updatedAt of the last website booking you applied, kept between runs; undefined before the first. */ lastSeen(): Promise; saveLastSeen(updatedAt: string): Promise; } /** A website booking, not an OTA one. An OTA booking would name the OTA and say CHANNEL_MANAGER. */ export const isWebsiteBooking = (booking: WebsiteBooking) => booking.channel.source === "DIRECT_WEB" && booking.channel.otaName === "Website"; /** * Call this from your webhook route once the signature is checked, then answer 2xx at once. Deliveries are * at-least-once: remember event.id too if your calendar cannot take the same booking twice. */ export async function onWebhookEvent(event: WebhookEvent, calendar: MyCalendar): Promise<"applied" | "ignored"> { switch (event.type) { case "direct.booking.created": // a guest booked: the room is off the count the channels hold already case "direct.booking.cancelled": // the guest or the hotel cancelled: the booking says CANCELLED, with cancellation.reason if (event.data.booking && isWebsiteBooking(event.data.booking)) { await calendar.setWebsiteBooking(event.data.booking); return "applied"; } return "ignored"; default: // channel.booking.* is an OTA booking: your existing code handles it. There is no direct.booking.modified. return "ignored"; } } interface WebsiteBookingsPage { since: string; items: WebsiteBooking[]; more: boolean; nextCursor: string | null; } /** * Apply every website booking changed since the last one you applied. since is on a booking's last change, so * a cancellation lists the booking again; the oldest change comes first. On the first run pass `firstSince`, * the date of the oldest booking your PMS needs to know of: with none, the API reads the last seven days. */ export async function catchUpWebsiteBookings(calendar: MyCalendar, propertyId?: number, firstSince?: string): Promise { const since = (await calendar.lastSeen()) ?? firstSince; let cursor: string | undefined; let applied = 0; let newest: string | undefined; for (;;) { // While `more` is true, ask again with cursor = nextCursor. A cursor replaces since. const page = await zs("/direct-bookings", { propertyId, query: { since: cursor ? undefined : since, limit: 100, cursor } }); for (const booking of page.items) { await calendar.setWebsiteBooking(booking); newest = booking.updatedAt; applied++; } if (!page.more || !page.nextCursor) break; cursor = page.nextCursor; } // Start the next read at the last change you saw: it lists that booking once more, which is harmless. if (newest) await calendar.saveLastSeen(newest); return applied; } export interface AvailabilityUpdate { roomTypeId: number; dateFrom: string; dateTo: string; /** The rooms left to sell: absolute, not a change. */ available: number; } /** * Your PMS's full push of room counts. The website bookings come first, so the counts you work out already * hold the rooms they took; the push then never reopens a room a guest has booked. */ export async function pushRoomCounts(calendar: MyCalendar, countsFromMyCalendar: () => Promise, propertyId?: number) { await catchUpWebsiteBookings(calendar, propertyId); const updates = await countsFromMyCalendar(); // read AFTER the catch-up, never before it return zs("/availability", { method: "PUT", body: { updates }, propertyId }); } ``` ## Guide: move a hotel to ZimmerStack Booking.com, Agoda and MakeMyTrip each connect a hotel to one channel manager at a time. A hotel cannot be on its old channel manager and on ZimmerStack for the same OTA, so there is no side-by-side run: your sandbox is the dry run, and the move is made one OTA at a time, each in minutes. 1. **Add the hotel** (You). In the partner portal. ZimmerStack activates it, usually the same day, ready for your live key. 2. **Send its structure and a year of calendar** (You). With the live key: the room types and rate plans (PUT /catalog/room-types, PUT /catalog/rate-plans), then rates, availability and stay rules for the whole horizon. No OTA sees any of it yet. Wait for GET /sync to read IN_SYNC. 3. **Ask each OTA to switch, a day ahead** (The hotel). In each extranet the hotel names the connectivity partner we give you when the hotel is set up. Booking.com: Account → Connectivity provider, then accept the agreement; Booking.com approves it. Agoda: YCS → Property settings → enable channel manager mode, then choose it. MakeMyTrip and Goibibo: ask in InGo to change the channel manager; MakeMyTrip then issues an access token. These are the hotel's own logins; nobody at ZimmerStack needs them. 4. **Connect, match, start selling** (Us with you, for your first hotel). On the hotel's page in the partner portal: Connect a channel, type what the OTA gave the hotel, match every room and rate, then Start selling. Starting sends the hotel's whole calendar to that OTA, and from that minute its new bookings, changes and cancellations reach you by webhook. For your first hotel ZimmerStack's team does this step with you on a call, one OTA at a time; you run the next hotels yourself. 5. **Switch that OTA off in the old channel manager** (You). Once the OTA has moved, the old channel manager no longer reaches it; switching it off there stops it trying. No duplicate and no missed booking: - **Feed both while you move.** Until every OTA has moved, your system keeps sending availability to the old channel manager and to ZimmerStack. A booking from either side lowers your count; send the new count to both. - **Upcoming bookings come again.** When Booking.com, Expedia or Airbnb starts selling, we import the hotel's upcoming bookings from that OTA and send each as channel.booking.created. You already hold them from the old channel manager: match on channel.otaName with channel.otaReservationCode and treat a match as the same booking. - **Older Agoda and MakeMyTrip bookings stay with you.** Those OTAs offer no import, so a booking made before the switch is not in ZimmerStack. If the OTA changes one after the switch, it reaches you about an hour later as channel.booking.created and then channel.booking.modified: match it the same way. If the OTA cancels one, it reaches you about an hour later as one channel.booking.cancelled, with the booking's status cancelled and no created before it: match it the same way. A cancellation like that changes no availability here. - **Move at a quiet hour.** One hotel at a time, every OTA in one sitting. That evening, check each extranet's reservation list against your system. Booking e-mails: The OTAs keep sending their booking e-mails to the reservation address set in their own extranet. Changing the channel manager does not change it, so a mailbox kept as a backup keeps working. ZimmerStack sends no e-mail of its own for an OTA booking: your system hears through the webhook (or GET /channel-bookings), and the hotel sees the booking on its bookings screen. Check each extranet's e-mail setting once after the move. ## The Node package: @zimmerstack/connect The official client for Node 20 or newer: zero dependencies, every request and answer typed from this contract. Install it instead of writing requests by hand: `npm install @zimmerstack/connect`. Page: https://docs.zimmerstack.com/sdk | The API's rule | What the package does | |---|---| | The key stays on a server | Refuses to start in a browser or in React Native. Sends the key to ZimmerStack only, never follows a redirect with it, and never prints it: not in an error, not when the client is logged. | | Budgets per minute | Reads the RateLimit header on every answer and waits before a budget runs out, instead of earning a 429. | | Writes are never a burst | Sends writes one at a time, in the order they were made. At most four reads at once. | | Retry only what passes with time | Retries a 429, a 5xx and a network failure with a growing wait, four attempts in all. Any other refusal is thrown at once and never resent. A wait longer than two minutes is given back to you. | | A retry must not write twice | Gives every write an idempotency key and reuses it on its own retries. A write the server keeps no such record for is not resent when its outcome is unknown. | | A request has a size | Splits a write at 1,000 updates or 5,000 cells, and folds single nights into ranges (grid.save). | | A refused key is not retried | After API_KEY_INVALID, API_KEY_REVOKED or API_KEY_EXPIRED it stops calling, so an address is never locked out by a loop. | | A test must not touch a real hotel | Refuses to write with a zsk_live_ key under a test runner (NODE_ENV=test, Vitest, Jest, node --test). | **The first calls**, with a new key: ```ts import { ZimmerStackError, addDays } from "@zimmerstack/connect"; import { zs } from "@/lib/zimmerstack"; /** The first calls to make with a new key: which hotel is this, what does it sell, and one price changed. */ export async function firstCalls(): Promise { // Which hotel, in which timezone and currency, and what this key may do. const property = await zs().property.get(); console.log(`${property.name}: ${property.currency}, ${property.timezone}, scopes ${property.scopes.join(", ")}`); // The grid for the next fortnight: rows are room types with their rate plans, columns are nights. const today = new Intl.DateTimeFormat("en-CA", { timeZone: property.timezone }).format(new Date()); // YYYY-MM-DD in the hotel's zone const grid = await zs().grid.load(today, addDays(today, 13)); const plan = grid.rows[0]?.plans[0]; if (!plan) return console.log("This property has no rate plan yet."); console.log(`${plan.ratePlan.name} tonight: ${plan.rate[today] ?? "no price set"}`); try { // Change one price (major units: 5200 = 5,200.00). Accepted means it is in ZimmerStack's record. const [accepted] = await zs().grid.save({ rates: [{ ratePlanId: plan.ratePlan.id, date: addDays(today, 7), rate: 5200 }] }); if (!accepted) return; // On its way to the channels: "landed", or still "pending" after five minutes. const batch = await zs().batches.wait(accepted.batchId); console.log(`${accepted.acceptedCells} night changed, ${batch.status}`); } catch (err) { if (!(err instanceof ZimmerStackError)) throw err; console.log(`Refused (${err.code}): ${err.message}`); // err.code is stable; err.message is for a person } } ``` **lib/zimmerstack.ts**: the one client of the app, and how a refusal is handed to the app's own frontend. ```ts import { ZimmerStack, ZimmerStackError } from "@zimmerstack/connect"; let client: ZimmerStack | undefined; /** * The one ZimmerStack client of this app. It reads the key from the environment variable * ZIMMERSTACK_CONNECT_KEY (zsk_test_… while you build). Server only: use it from route handlers and * server actions, never from a component marked "use client". */ export function zs(): ZimmerStack { return (client ??= new ZimmerStack()); } /** * Turn a refusal into an answer for your own frontend: the API's sentence for the person, its stable * code for your UI to branch on, and when to try again if it said so. The client has already retried * what was worth retrying, so nothing here loops. */ export function refusal(err: unknown): Response { if (!(err instanceof ZimmerStackError)) throw err; const status = err.status === 429 ? 429 : err.status >= 400 && err.status < 500 ? 400 : 502; return Response.json({ error: err.message, code: err.code, retryAfterSeconds: err.retryAfterSeconds ?? null }, { status }); } ``` **app/api/grid/route.ts**: the rate grid, read and saved. ```ts import type { GridEdits } from "@zimmerstack/connect"; import { refusal, zs } from "@/lib/zimmerstack"; // Your own sign-in decides who may call these routes: check it first, in both handlers. /** GET /api/grid?from=2026-12-01&to=2026-12-14: rows are room types with their rate plans, columns are nights. */ export async function GET(request: Request): Promise { const { searchParams } = new URL(request.url); const from = searchParams.get("from"); const to = searchParams.get("to"); if (!from || !to) return Response.json({ error: "from and to are required (YYYY-MM-DD)" }, { status: 400 }); try { return Response.json(await zs().grid.load(from, to)); } catch (err) { return refusal(err); } } /** PUT /api/grid with what the person changed: single nights, only the ones that changed. */ export async function PUT(request: Request): Promise { const edits = (await request.json()) as GridEdits; try { // Nights are folded into ranges and sent one request per resource. Each answer carries a batchId: // the values are in ZimmerStack's record and on their way to the channels. const accepted = await zs().grid.save(edits); return Response.json({ accepted }); } catch (err) { return refusal(err); } } ``` **app/api/channels/route.ts**: a different price per channel. ```ts import { MODIFIER_TAKES_EFFECT, channelPrice, type ModifierStep } from "@zimmerstack/connect"; import { refusal, zs } from "@/lib/zimmerstack"; /** GET /api/channels: each connected channel, the steps it holds, and what a price of 4,500 becomes there. */ export async function GET(): Promise { try { const { channels, asOf } = await zs().channels.list(); return Response.json({ asOf, // Show this sentence where the person saves a modifier. takesEffect: MODIFIER_TAKES_EFFECT, channels: channels.map((channel) => ({ channelId: channel.channelId, name: channel.title ?? channel.kind, // [] = prices go as they are; null = a rule set by hand that this API cannot express. modifier: channel.modifier, example: channel.modifier ? channelPrice(4500, channel.modifier) : null, })), }); } catch (err) { return refusal(err); } } /** * PUT /api/channels { channelId, steps }: the person saved a channel's modifier. * One call moves every price sent to that channel from then on: call it from that Save button only. */ export async function PUT(request: Request): Promise { const { channelId, steps } = (await request.json()) as { channelId: string; steps: ModifierStep[] }; try { return Response.json(await zs().channels.setModifier(channelId, steps)); } catch (err) { return refusal(err); } } /** * POST /api/channels: the "Apply to nights already on sale" button. Prices already on a channel keep the * old modifier until they are sent again; this sends them again, unchanged. A few times a day per hotel. */ export async function POST(): Promise { try { return Response.json(await zs().rates.resend(), { status: 202 }); } catch (err) { return refusal(err); } } ``` **app/api/webhooks/zimmerstack/route.ts**: OTA bookings arriving. ```ts import { ZimmerStackWebhookError, isOtaBookingEvent, isWebsiteBookingEvent, verifyWebhook, type OtaBookingEvent, type WebhookEvent, type WebsiteBookingEvent } from "@zimmerstack/connect"; /** POST /api/webhooks/zimmerstack: a booking arrived, changed or was cancelled, from an OTA or from the hotel's own website. */ export async function POST(request: Request): Promise { let event: WebhookEvent; try { // The body exactly as it arrived: read it as text, before any JSON parsing. event = await verifyWebhook(await request.text(), request.headers, process.env.ZIMMERSTACK_WEBHOOK_SECRET ?? ""); } catch (err) { if (err instanceof ZimmerStackWebhookError) return new Response(null, { status: 400 }); throw err; } // Deliveries are at-least-once: remember event.id and skip one you have already handled. if (isOtaBookingEvent(event)) { // channel.booking.created · .modified · .cancelled: a booking an OTA sent. await saveBooking(event); } else if (isWebsiteBookingEvent(event)) { // direct.booking.created · .cancelled: a guest booked, or cancelled, on the hotel's own website. The // endpoint receives these only when it lists both types. There is no modified event. await applyWebsiteBooking(event); } // Answer fast (within a few seconds) and do slow work afterwards: a slow answer is retried. return new Response(null, { status: 204 }); } /** Yours to write: store event.data.booking under its reference, in your own database. */ async function saveBooking(event: OtaBookingEvent): Promise { void event; } /** * Yours to write: put the booking in your own calendar. A website booking takes one room off the count the * channels hold at once, so a cancelled one gives it back; apply it BEFORE your next push of room counts, * or that push puts the sold room back on sale. */ async function applyWebsiteBooking(event: WebsiteBookingEvent): Promise { void event; } ``` ## Guide: build a rate grid Rows are room types, each followed by its rate plans. Columns are nights. Rooms left to sell belong to the room type; the price and the stay rules belong to the rate plan. 1. `GET /catalog` gives the rows. Cache it for ten minutes; ids come from here and nowhere else. 2. Three reads give every cell of the window: `GET /availability`, `GET /rates` and `GET /restrictions`, each with `?from=YYYY-MM-DD&to=YYYY-MM-DD`. Draw 14 to 60 nights; load the next window when the person scrolls. 3. The person edits cells. Keep one pending edit per cell on the screen; send nothing while they type. 4. On Save, fold the edits into ranges (consecutive nights of one row with the same value become one `dateFrom`..`dateTo`) and send one `PUT` per resource, one after another. 5. Each `202` carries a `batchId`. Show "saved, syncing" and ask `GET /batches/{batchId}` at most every 15 seconds until it says `landed` (or `failed` with `lastError`). 6. Read the window again after a save, when a `channel.booking.*` or `direct.booking.*` webhook names those nights, and when the person asks. Never on a timer. The four files below are the whole of it. They are checked against this contract on every change to the site: every body they send passes the schema above. **zimmerstack.ts**: the client. Server only; paces itself from the RateLimit header, retries what passes with time, never anything else. ```ts /** * A small server-side client for the ZimmerStack Connect API. No dependencies; Node 20 or newer. * * SERVER ONLY. The key can change a hotel's prices on every channel: it never goes to a browser, * a mobile app, a public repository or a log line. Your own frontend calls YOUR server, and your * server calls ZimmerStack with this file. */ const BASE = "https://api.zimmerstack.com/api/v1/connect-api/v1"; export class ZimmerStackError extends Error { constructor( public status: number, /** The stable code to branch on (RATE_LIMITED, RATE_OUT_OF_BAND, …). Messages are for people and may change. */ public code: string, message: string, public details?: unknown, public retryAfterSeconds?: number ) { super(message); this.name = "ZimmerStackError"; } } export interface ZsOptions { method?: "GET" | "PUT" | "POST" | "DELETE"; query?: Record; body?: unknown; /** Company keys only: the hotel this request acts on (GET /properties lists them). */ propertyId?: number; } interface Envelope { message?: string; data?: { code?: string; details?: unknown } & Record; } const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); const MAX_ATTEMPTS = 4; /** When a budget is nearly used up, the moment it refills. Every call waits for it instead of earning a 429. */ let resumeAt = 0; function notePace(res: Response) { // RateLimit: "key";r=117;t=42, "key-writes";r=29;t=42 (r = requests left, t = seconds until the window refills) for (const part of (res.headers.get("ratelimit") ?? "").split(",")) { const left = /;r=(\d+)/.exec(part); const refill = /;t=(\d+)/.exec(part); if (left && refill && Number(left[1]) <= 2) resumeAt = Math.max(resumeAt, Date.now() + Number(refill[1]) * 1000); } } export async function zs(path: string, opts: ZsOptions = {}): Promise { if (typeof window !== "undefined") throw new Error("The ZimmerStack key must stay on your server"); const key = process.env.ZIMMERSTACK_CONNECT_KEY; // zsk_test_… while you build, zsk_live_… in production if (!key) throw new Error("ZIMMERSTACK_CONNECT_KEY is not set"); const method = opts.method ?? "GET"; const url = new URL(BASE + path); for (const [name, value] of Object.entries(opts.query ?? {})) if (value !== undefined) url.searchParams.set(name, String(value)); const headers: Record = { authorization: "Bearer " + key, accept: "application/json" }; if (opts.propertyId) headers["x-zs-property"] = String(opts.propertyId); if (opts.body !== undefined) headers["content-type"] = "application/json"; // One idempotency key per write, reused on every retry of it, so a write that timed out can never land twice. if (method !== "GET") headers["x-idempotency-key"] = crypto.randomUUID(); const body = opts.body === undefined ? undefined : JSON.stringify(opts.body); for (let attempt = 1; ; attempt++) { if (resumeAt > Date.now()) await sleep(resumeAt - Date.now()); let res: Response; try { res = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(30_000) }); } catch (err) { if (attempt >= MAX_ATTEMPTS) throw err; await sleep(1000 * 2 ** (attempt - 1)); // the network failed: 1 s, 2 s, 4 s continue; } notePace(res); const json = (await res.json().catch(() => null)) as Envelope | null; if (res.ok) return json?.data as T; const code = json?.data?.code ?? "HTTP_" + res.status; const retryAfter = Number(res.headers.get("retry-after")) || undefined; // Retry only what passes with time: a used-up budget (429), a fault on our side (5xx), and a duplicate // of a request still running. Every other 4xx is a verdict on the request: fix it, never resend it. const passesWithTime = res.status === 429 || res.status >= 500 || code === "IDEMPOTENCY_IN_FLIGHT"; // A long Retry-After (an hourly or daily budget, a pause) is not worth holding a request open for. if (!passesWithTime || attempt >= MAX_ATTEMPTS || (retryAfter ?? 0) > 120) { throw new ZimmerStackError(res.status, code, json?.message ?? res.statusText, json?.data?.details, retryAfter); } await sleep(((retryAfter ?? 2 ** (attempt - 1)) + Math.random()) * 1000); // 1 s, 2 s, 4 s, each with a little jitter } } ``` **grid.ts**: read the grid, fold edits into ranges, write them, watch a batch land. ```ts /** * The rate grid, read and written: rows are room types with their rate plans, columns are nights. * Runs on your server, on top of zimmerstack.ts. */ import { zs } from "./zimmerstack"; export interface Restrictions { stopSell: boolean | null; closedToArrival: boolean | null; closedToDeparture: boolean | null; minStayArrival: number | null; minStayThrough: number | null; maxStay: number | null; } export interface Grid { from: string; to: string; currency: string; /** One column per night, YYYY-MM-DD in the hotel's own timezone. */ dates: string[]; rows: Array<{ roomType: { id: number; name: string }; /** date -> rooms of this type left to sell */ available: Record; plans: Array<{ ratePlan: { id: number; name: string; mealPlan: string | null }; /** date -> nightly price in MAJOR units (rupees, euros) */ rate: Record; /** date -> the stay rules; null = no rule set for that field */ restrictions: Record; }>; }>; } interface Catalog { currency: string; roomTypes: Array<{ id: number; name: string }>; ratePlans: Array<{ id: number; roomTypeId: number; name: string; mealPlan: string | null }>; } const DAY = 86_400_000; const ms = (date: string) => Date.parse(date + "T00:00:00Z"); /** * Every night from `from` to `to`, both included. Dates are plain calendar strings: the arithmetic runs * in UTC so the server's or the browser's timezone can never move a night. */ export function eachDate(from: string, to: string): string[] { const out: string[] = []; for (let t = ms(from); t <= ms(to); t += DAY) out.push(new Date(t).toISOString().slice(0, 10)); return out; } // The catalog changes when the owner adds a room type or a plan, not while a grid is open: keep it ten minutes. const catalogs = new Map(); async function getCatalog(propertyId?: number): Promise { const hit = catalogs.get(propertyId ?? 0); if (hit && Date.now() - hit.at < 10 * 60_000) return hit.value; const value = await zs("/catalog", { propertyId }); catalogs.set(propertyId ?? 0, { at: Date.now(), value }); return value; } /** Three reads for the whole window (four the first time). A window may span up to 500 days; a screen needs 14 to 60. */ export async function loadGrid(from: string, to: string, propertyId?: number): Promise { const query = { from, to }; const [catalog, availability, rates, restrictions] = await Promise.all([ getCatalog(propertyId), zs<{ cells: Array<{ roomTypeId: number; date: string; available: number }> }>("/availability", { query, propertyId }), zs<{ cells: Array<{ ratePlanId: number; date: string; rateMinor: number }> }>("/rates", { query, propertyId }), zs<{ cells: Array<{ ratePlanId: number; date: string } & Restrictions> }>("/restrictions", { query, propertyId }), ]); const rows: Grid["rows"] = catalog.roomTypes.map((roomType) => ({ roomType: { id: roomType.id, name: roomType.name }, available: {}, plans: catalog.ratePlans .filter((plan) => plan.roomTypeId === roomType.id) .map((plan) => ({ ratePlan: { id: plan.id, name: plan.name, mealPlan: plan.mealPlan }, rate: {}, restrictions: {} })), })); const rowOf = new Map(rows.map((row) => [row.roomType.id, row])); const planOf = new Map(rows.flatMap((row) => row.plans.map((plan) => [plan.ratePlan.id, plan] as const))); for (const cell of availability.cells) { const row = rowOf.get(cell.roomTypeId); if (row) row.available[cell.date] = cell.available; } for (const cell of rates.cells) { const plan = planOf.get(cell.ratePlanId); if (plan) plan.rate[cell.date] = cell.rateMinor / 100; // read in minor units, shown and written in major } for (const { ratePlanId, date, ...rules } of restrictions.cells) { const plan = planOf.get(ratePlanId); if (plan) plan.restrictions[date] = rules; } return { from, to, currency: catalog.currency, dates: eachDate(from, to), rows }; } /** What the person changed on the screen: single nights, only the ones that changed. */ export interface GridEdits { availability?: Array<{ roomTypeId: number; date: string; available: number }>; /** `rate` in MAJOR units. To close a night send stopSell, never a zero price. */ rates?: Array<{ ratePlanId: number; date: string; rate: number }>; restrictions?: Array<{ ratePlanId: number; date: string; stopSell?: boolean; closedToArrival?: boolean; closedToDeparture?: boolean; minStayArrival?: number; minStayThrough?: number; maxStay?: number; }>; } export interface Range { id: number; dateFrom: string; dateTo: string; value: V; } /** * Fold single-night edits into the fewest ranges: consecutive nights of one row that carry the same value * become one { dateFrom, dateTo }. Thirty nights at one price are one update, not thirty. */ export function toRanges(cells: Array<{ id: number; date: string; value: V }>): Array> { const sorted = [...cells].sort((a, b) => a.id - b.id || (a.date < b.date ? -1 : a.date > b.date ? 1 : 0)); const out: Array> = []; for (const cell of sorted) { const last = out[out.length - 1]; if (last && last.id === cell.id && JSON.stringify(last.value) === JSON.stringify(cell.value) && ms(cell.date) - ms(last.dateTo) <= DAY) { last.dateTo = cell.date; } else { out.push({ id: cell.id, dateFrom: cell.date, dateTo: cell.date, value: cell.value }); } } return out; } const nights = (range: { dateFrom: string; dateTo: string }) => (ms(range.dateTo) - ms(range.dateFrom)) / DAY + 1; /** One request carries at most 1,000 updates and 5,000 cells (a cell is one row on one night). */ export function chunk(updates: U[], maxUpdates = 1000, maxCells = 5000): U[][] { const out: U[][] = []; let current: U[] = []; let cells = 0; for (const update of updates) { if (current.length > 0 && (current.length >= maxUpdates || cells + nights(update) > maxCells)) { out.push(current); current = []; cells = 0; } current.push(update); cells += nights(update); } if (current.length > 0) out.push(current); return out; } export interface WriteAccepted { batchId: string; resource: "availability" | "rates" | "restrictions"; acceptedCells: number; noopCells: number; /** Groups our record refused, with the reason. The rest of the request landed. */ rejected: Array<{ cells: number; error: string }>; } /** * Save what changed: one PUT per resource, ranges not nights, one after another (never a burst). * Each answer is a 202 with a batchId: the values are in ZimmerStack's record and on their way to the channels. */ export async function saveGrid(edits: GridEdits, propertyId?: number): Promise { const accepted: WriteAccepted[] = []; const put = async (path: string, updates: Array<{ dateFrom: string; dateTo: string }>) => { for (const part of chunk(updates)) accepted.push(await zs(path, { method: "PUT", body: { updates: part }, propertyId })); }; if (edits.availability?.length) { const ranges = toRanges(edits.availability.map((e) => ({ id: e.roomTypeId, date: e.date, value: e.available }))); await put("/availability", ranges.map((r) => ({ roomTypeId: r.id, dateFrom: r.dateFrom, dateTo: r.dateTo, available: r.value }))); } if (edits.rates?.length) { const { currency } = await getCatalog(propertyId); // a rate must be sent in the property's own currency const ranges = toRanges(edits.rates.map((e) => ({ id: e.ratePlanId, date: e.date, value: e.rate }))); await put("/rates", ranges.map((r) => ({ ratePlanId: r.id, dateFrom: r.dateFrom, dateTo: r.dateTo, rate: r.value, currency }))); } if (edits.restrictions?.length) { const ranges = toRanges(edits.restrictions.map(({ ratePlanId, date, ...rules }) => ({ id: ratePlanId, date, value: rules }))); await put("/restrictions", ranges.map((r) => ({ ratePlanId: r.id, dateFrom: r.dateFrom, dateTo: r.dateTo, ...r.value }))); } return accepted; } export interface BatchStatus { batchId: string; status: "landed" | "pending" | "failed"; pendingCells: number; lastError: string | null; } /** * Has a write reached the channels? Poll no more often than every 15 seconds, and stop: availability lands * in seconds and prices within a minute or two, so after five minutes show "still syncing" and let the * person look again later (GET /sync answers for the whole property). */ export async function waitForBatch(batchId: string, propertyId?: number): Promise { for (let i = 0; ; i++) { const batch = await zs("/batches/" + batchId, { propertyId }); if (batch.status !== "pending" || i >= 20) return batch; await new Promise((resolve) => setTimeout(resolve, 15_000)); } } ``` **route.ts**: your own endpoint between your screen and ZimmerStack. ```ts /** * Your own endpoint, between your screen and ZimmerStack (here a Next.js route handler: app/api/grid/route.ts; * the same two functions fit Express, Fastify, Laravel or Django). The browser talks to this, never to * api.zimmerstack.com, so the key stays on the server. */ import { loadGrid, saveGrid, type GridEdits } from "./grid"; import { ZimmerStackError } from "./zimmerstack"; const DATE = /^\d{4}-\d{2}-\d{2}$/; /** Replace with your own sign-in check: this endpoint can change a hotel's prices on every channel. */ async function requireStaff(req: Request): Promise { return req.headers.has("cookie"); } /** Pass ZimmerStack's refusal on in a shape your screen can show: the code to branch on, the sentence to print. */ function refusal(err: unknown): Response { if (err instanceof ZimmerStackError) { const status = err.status === 429 ? 429 : err.status >= 500 ? 502 : 400; return Response.json({ code: err.code, message: err.message, details: err.details, retryAfterSeconds: err.retryAfterSeconds }, { status }); } return Response.json({ code: "UPSTREAM_UNREACHABLE", message: "ZimmerStack could not be reached. Nothing was changed." }, { status: 502 }); } // GET /api/grid?from=2026-11-01&to=2026-11-30 export async function GET(req: Request) { if (!(await requireStaff(req))) return Response.json({ code: "UNAUTHENTICATED" }, { status: 401 }); const { searchParams } = new URL(req.url); const from = searchParams.get("from") ?? ""; const to = searchParams.get("to") ?? ""; if (!DATE.test(from) || !DATE.test(to)) return Response.json({ code: "BAD_RANGE", message: "from and to are YYYY-MM-DD" }, { status: 400 }); try { return Response.json(await loadGrid(from, to)); } catch (err) { return refusal(err); } } // PUT /api/grid { availability?: […], rates?: […], restrictions?: […] } only the cells that changed export async function PUT(req: Request) { if (!(await requireStaff(req))) return Response.json({ code: "UNAUTHENTICATED" }, { status: 401 }); const edits = (await req.json()) as GridEdits; try { return Response.json({ batches: await saveGrid(edits) }, { status: 202 }); } catch (err) { return refusal(err); } } ``` **RateGrid.tsx**: the smallest working screen. ```tsx "use client"; /** * The smallest working grid: read once, edit prices in place, save only what changed, in one request. * It talks to YOUR endpoint (/api/grid), never to ZimmerStack. Style it and grow it from here. */ import * as React from "react"; import type { Grid, GridEdits } from "./grid"; export function RateGrid({ from, to }: { from: string; to: string }) { const [grid, setGrid] = React.useState(null); // One entry per edited cell, keyed "ratePlanId:date": typing in a cell twice is still one change. const [edits, setEdits] = React.useState>(new Map()); const [note, setNote] = React.useState(""); const [version, setVersion] = React.useState(0); // Read when the window changes or after a save, never on a timer. Refresh on a booking webhook or when asked. React.useEffect(() => { let live = true; fetch("/api/grid?from=" + from + "&to=" + to) .then((res) => (res.ok ? res.json() : Promise.reject(new Error("not loaded")))) .then((data: Grid) => { if (live) setGrid(data); }) .catch(() => { if (live) setNote("The grid could not be loaded. Check your connection and reload."); }); return () => { live = false; }; }, [from, to, version]); const save = async () => { const rates: GridEdits["rates"] = [...edits].map(([key, rate]) => { const [ratePlanId, date] = key.split(":"); return { ratePlanId: Number(ratePlanId), date, rate }; }); setNote("Saving…"); const res = await fetch("/api/grid", { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ rates }) }); if (!res.ok) { const refusal = await res.json().catch(() => null); setNote(refusal?.message ?? "Not saved. Your changes are still on the screen."); // fix and save again return; } setEdits(new Map()); setNote("Saved. Prices reach the channels within a minute or two."); setVersion((v) => v + 1); // read back what the record now holds }; if (!grid) return

{note || "Loading the grid…"}

; return (
{grid.dates.map((date) => ( ))} {grid.rows.map((row) => ( {grid.dates.map((date) => ( ))} {row.plans.map((plan) => ( {grid.dates.map((date) => { const key = plan.ratePlan.id + ":" + date; const closed = plan.restrictions[date]?.stopSell === true; return ( ); })} ))} ))}
Room / plan {date.slice(5)}
{row.roomType.name} · rooms to sell{row.available[date] ?? "–"}
{plan.ratePlan.name} { const rate = Number(event.target.value); const changed = Number.isFinite(rate) && rate >= 1 && rate !== plan.rate[date]; setEdits((prev) => { const next = new Map(prev); if (changed) next.set(key, rate); else next.delete(key); return next; }); }} />

{note}

); } ``` ## Guide: prices that differ per channel There is one grid per hotel: one price per rate plan per night, sent to every channel that plan is mapped to. What differs per channel is the channel's **modifier**: up to five ordered steps (raise or lower, by a percentage or a fixed amount in major units) applied to every price sent to that channel. 1. `GET /channels`: find the channel (channelId, kind) and read the steps it holds. 2. `PUT /channels/{channelId}/modifier` with the whole list of steps; [] removes the modifier. 3. `POST /rates/resend` if nights already on the channel should move too, then watch rates.dirtyCells on `GET /sync` fall to 0. - **When it applies.** A modifier applies to prices sent to the channel after the change. Prices already on the channel stay as they are until those nights are sent again. Print that sentence where the person saves a modifier. - **Scope.** Setting one needs `channel-modifiers:write`, which the hotel's owner grants apart from `ari:write`. Without it the route answers `403 SCOPE_MISSING`: ask the owner, do not look for another way. - **One call moves every price on that channel.** Call `PUT /channels/{channelId}/modifier` only when a person saved the setting. Never from a loop, a timer, a migration, a seed script or a test against a `zsk_live_` key. - **The band.** The steps together must stay between 50% lower and 100% higher, or the answer is `422 MODIFIER_OUT_OF_BAND` and nothing changes. Check it on the screen first. - **Budgets.** 6 modifier changes and 3 re-sends per hotel per day. `POST /rates/resend` is a deliberate button for a person ("apply to nights already on sale"); never call it automatically, and never to "make sure". - **Re-sending the same price through `PUT /rates` does nothing**: an unchanged value is dropped. The re-send is the only way a night already on a channel picks a new modifier up. - **A shared connection.** `409 CHANNEL_SHARED`: the connection serves several hotels and its modifier is not yours to set. Show the message; do not retry. - **In the grid.** GET /rates always answers the price before any modifier. What a channel is sent is that price with the channel's steps applied in order. Show the channel's price beside the base price; never write it back as the rate. - **A rate plan per OTA** is the other way, for one OTA needing its own price on particular nights: a second plan (`PUT /catalog/rate-plans`) the hotel maps to that OTA in the ZimmerStack Channels app, priced with `PUT /rates` like any plan. - **Sandbox.** A sandbox has three pretend channels (Booking.com, MakeMyTrip, Agoda) so the whole workflow can be tried with a test key; nothing leaves our record. **modifiers.ts**: read each channel's modifier, compute what a channel is sent, set a modifier, send the prices again. ```ts /** * Prices that differ per channel. One price per rate plan per night goes to every channel; a channel's * modifier is what differs: ordered steps the channel manager applies to every price it sends that channel. * Runs on your server, on top of zimmerstack.ts. The key needs the scope channel-modifiers:write to set one. */ import { zs } from "./zimmerstack"; export interface ModifierStep { action: "increase" | "decrease"; type: "percent" | "fixed"; /** 18 with "percent" is 18 %; 200 with "fixed" is 200.00 in the property's currency. Always positive. */ value: number; } export interface Channel { channelId: string; /** BookingCom, GoMMT, Agoda, Airbnb, Expedia, … */ kind: string; title: string | null; /** [] = prices go as they are. null = a rule set by hand that this API cannot express; setting one replaces it. */ modifier: ModifierStep[] | null; } /** The connected channels, each with the steps it holds. Answered from ZimmerStack's record: read it when the screen opens. */ export async function listChannels(propertyId?: number): Promise { const out = await zs<{ channels: Channel[] }>("/channels", { propertyId }); return out.channels; } /** * What a channel is sent for a price, in MAJOR units: the steps applied in order. Your grid holds the price * before any modifier (that is what GET /rates returns); use this to show "on Booking.com" beside it. */ export function channelPrice(rate: number, steps: ModifierStep[]): number { let minor = Math.round(rate * 100); for (const step of steps) { const sign = step.action === "decrease" ? -1 : 1; minor = step.type === "percent" ? minor * (1 + (sign * step.value) / 100) : minor + sign * Math.round(step.value * 100); } return Math.round(minor) / 100; } export interface ModifierResult { channelId: string; modifier: ModifierStep[]; /** false when the channel already held exactly these steps: nothing was sent and nothing was counted. */ changed: boolean; notice: string; } /** * Replace a channel's steps with the list given ([] removes them). 200 means the channel holds them. * * ONE CALL MOVES EVERY PRICE SENT TO THAT CHANNEL FROM THEN ON. Call it when a person saved the setting, * never from a loop, a timer or a test against a live key. Prices already on the channel stay as they are * until those nights are sent again: see resendRates. */ export async function setModifier(channelId: string, steps: ModifierStep[], propertyId?: number): Promise { return zs("/channels/" + encodeURIComponent(channelId) + "/modifier", { method: "PUT", body: { steps }, propertyId }); } export interface ResendAccepted { from: string; to: string; /** Rate-plan nights marked to be sent again. Watch rates.dirtyCells on GET /sync fall to 0. */ cells: number; watch: string; } /** * Send the property's prices to the channels again, unchanged, so nights already there pick the current * modifiers up. A hotel may ask a few times a day: offer it as a button after a modifier change, and never * call it automatically. Re-sending the same price through PUT /rates does nothing: an unchanged value is * dropped before anything is sent. */ export async function resendRates(propertyId?: number): Promise { return zs("/rates/resend", { method: "POST", propertyId }); } ``` ## Room counts A room type's roomCount is how many rooms of that type the channels may sell: the channel manager never sells more, even when the availability you send is higher (the 202's warnings name it). On a hotel that uses ZimmerStack only as its channel manager, change it by sending the room type again to PUT /catalog/room-types with the new roomCount: the channel manager takes it first, then our record; a count below the rooms holding upcoming stays is refused (409 CATALOG_CONFLICT). On a hotel that runs the ZimmerStack PMS the count is its room list's: a different value is not written, and the item's notice says so. To sell fewer rooms for some nights only, lower the availability instead. ## The sandbox - The owner creates a sandbox from a real property (admin → Developers → API keys, Channels → Integrations): a copy of its room types and rate plans that no channel ever sees. Keys minted there start with zsk_test_ and work ONLY there; a live key never reaches it. - Every route behaves as in production. A push lands in our record and stops: GET /sync reports IN_SYNC and GET /batches/{batchId} reports landed within a minute, through the same code path as a live property. GET /property says sandbox: true. - POST /sandbox/bookings/{bookingId}/modify sends a modified revision — new dates, length, rooms or guest — and the REAL channel.booking.modified webhook with changes and previous, the old nights back on availability and the new ones off. - POST /sandbox/bookings simulates an OTA booking end to end — the booking, the sandbox's availability moved down, the inventory event, and the REAL channel.booking.created webhook to every endpoint registered on the sandbox. POST /sandbox/bookings/{bookingId}/cancel does the same for a cancellation. With otaName "Website" the booking is one made on the hotel's own website instead, and the events are direct.booking.created and direct.booking.cancelled (x-zimmerstack.directBookings). A live key gets 403 SANDBOX_ONLY. - The same budgets as production (one sandbox per owner, up to five per software partner, at most five keys on each). Nothing you do there is billed or pushed to a channel. - Ask the owner for a zsk_live_ key on the real property, swap the key, keep the code. - A hotel owner holds one sandbox. A software partner holds up to five, one per hotel it is about to connect, each with its own property id and test keys: name it after the hotel and press Add a sandbox in the partner portal's Developers section. A test company key and a test company webhook reach all of them.