# ZimmerStack Connect API: rules for AI coding agents

You are writing software against the ZimmerStack Connect API. ZimmerStack is a hotel's channel manager: every price, room count and stay rule written through this API is sent to the hotel's online travel agents (Booking.com, MakeMyTrip, Agoda, Airbnb, Expedia and others), and guests book at what you wrote. A wrong write costs a real hotel real money within a minute. Follow this file exactly. Where it and your habits disagree, this file wins.

Source: https://docs.zimmerstack.com/agents.md, generated 2026-11-17 from the live API contract (ZimmerStack Connect API v1). The numbers below are the server's own; when https://docs.zimmerstack.com/changelog moves, download this file again.

## Where the truth is

- The whole reference in one file, written for you: https://docs.zimmerstack.com/llms-full.txt
- The OpenAPI 3.1 contract (schemas, a sample of every request, every limit and error code): https://api.zimmerstack.com/api/v1/public/connect-api/contract
- The pages people read: https://docs.zimmerstack.com
- Never invent a route, a field, a header, a scope or an id. If the contract does not have it, it does not exist. Room type and rate plan ids come from `GET /catalog` and nowhere else.

## The API on one screen

- Base URL: `https://api.zimmerstack.com/api/v1/connect-api/v1`
- Auth: `Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY` on every request, and nowhere else (never in: query string, x-api-key, user-api-key).
- A key starts `zsk_test_` (a sandbox no channel sees) or `zsk_live_` (a real hotel). A hotel key is one property. A software vendor's company key names the hotel on every request: `X-ZS-Property: <id from GET /properties>`.
- No key yet? A hotel's owner makes one (Admin → Developers → API keys). A software company signs itself up, free and with no call, at https://www.zimmerstack.com/partners/pms-companies#join (its sandbox is made at sign-up) and makes test company keys in the partner portal, https://partner.zimmerstack.com/login (Developers).
- Every answer is `{ "statuscode", "message", "data" }`. Read `data`. On a refusal branch on `data.code`, which is stable; never on `message`, which is for people and may change.
- `GET /property` works on every key: the property's timezone and currency, the key's scopes, its own limits and how much of them it has used.

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

## On Node: use the official package, not hand-written requests

`npm install @zimmerstack/connect` (Node 20 or newer, zero dependencies, typed from this contract). `new ZimmerStack()` reads `ZIMMERSTACK_CONNECT_KEY`; make one per process and reuse it. Reference: https://docs.zimmerstack.com/sdk

It keeps these rules by itself, so do not re-implement them and do not wrap its calls in your own retry, queue or pacing:

- 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).

- Its own rules file ships inside it: `node_modules/@zimmerstack/connect/AGENTS.md`. Read it; where it names a method, use that method.
- It carries an MCP server: `npx -y @zimmerstack/connect mcp`. If it is connected, look routes, types, limits and codes up with `zimmerstack_reference` and try a body on the sandbox with `zimmerstack_sandbox_write` before writing the code that sends it. It refuses a live key.
- The grid is `zs.grid.load(from, to)` and `zs.grid.save(edits)`; a channel's price is `zs.channels.list()`, `zs.channels.setModifier(channelId, steps)` and `zs.rates.resend()`; a webhook is `verifyWebhook(rawBody, headers, secret)`. The hotel's own website bookings (from @zimmerstack/connect 0.3.0): `isWebsiteBookingEvent(event)` and `zs.directBookings.all({ since })`.
- A refusal is a `ZimmerStackError`: branch on `err.code`, show `err.message`, and never resend unless `err.retryable`.
- Everything below still applies: what the package cannot decide for you is WHEN to write (on a person's own save, never on a timer) and WHERE the key lives.

## Rules you must not break

### 1. The key is a secret that moves money

- It lives in one server-side environment variable, `ZIMMERSTACK_CONNECT_KEY`. Never in browser or mobile code, never in a variable the build exposes to the client (`NEXT_PUBLIC_*`, `VITE_*`, `EXPO_PUBLIC_*`, `REACT_APP_*`), never in the repository, a log line, an error message, a URL or a prompt.
- The browser calls the integrator's own backend, and only that backend calls ZimmerStack. That backend route gets the integrator's own sign-in check: it can change a hotel's prices.
- Add `.env` to `.gitignore` before writing the key into it. Commit `.env.example` with the variable's name and no value.
- Build and test with a `zsk_test_` key. Never run tests, seed scripts, load tests, migrations or experiments with a `zsk_live_` key. If the only key you were given is live, stop and ask the person for a sandbox key.
- Print at most the first 12 characters of a key.
- Ask the hotel for the fewest scopes the feature needs, and for the server's public IP addresses on the key's allowlist.

### 2. Pacing: the limits are enforced, and an integration that ignores them is paused

Per minute: 120 requests and 30 writes per key; 300 requests and 60 writes per hotel across all its keys; 240 requests per IP address. One request: at most 1,000 updates, 5,000 cells (a cell is one room type or rate plan on one night) and 1,048,576 bytes. Per hotel: at least 10,000 changed cells an hour and 30,000 a day. Writes reach from today to today + 365 days; a read spans at most 500 days.

- Do not race the limits. Every answer carries `RateLimit` (`r` = requests left, `t` = seconds until the window refills): slow down before `r` reaches 0. `GET /property` carries the hotel's own `limits` and `usage`.
- Write ranges, not nights. One update with `dateFrom` and `dateTo` (and `days` for a weekday pattern) per run of equal values. Never one request per night, per row or per cell.
- Write on change only. Send the cells the person changed. Never re-send a calendar on a timer, on page load, on start-up or "to be safe".
- One write at a time per hotel. No `Promise.all` over writes, no parallel workers writing the same hotel.
- Edits wait for an explicit Save (or two quiet seconds), then go as one `PUT` per resource.
- Three reads draw a whole grid window. Cache `GET /catalog` for ten minutes. Never read in a loop per night or per row. Do not poll the grid.
- Ask `GET /batches/{batchId}` or `GET /sync` at most every 15 seconds, and stop after about five minutes.
- Bookings arrive by webhook. `GET /channel-bookings` (OTA bookings) and `GET /direct-bookings` (website bookings) recover a missed delivery; they are not polling loops.
- `429`: wait the `Retry-After` seconds the answer names, then resend the same request with the same `x-idempotency-key`. If that wait is longer than two minutes (an hourly or daily budget, or a pause), stop, keep the unsent changes, and tell the person.
- `5xx` or a network error: retry after 1, 2, then 4 seconds, three retries at most, same idempotency key.
- Never retry any other `4xx`. It is a verdict on the request: fix the request. No retry without a cap, no retry inside a retry.

### 3. Writes

- Values are absolute. `available` is the number of rooms left to sell on that night, not a change to it.
- Money: send `rate` in MAJOR units (4500 is four thousand five hundred rupees) with the property's `currency`; reads return `rateMinor` in MINOR units (450000). Convert in exactly one place. Prices are whole major units.
- A price is 1 to 21,474,836. To close a night send `stopSell: true` through `PUT /restrictions`; never a price of 0 or a token price.
- A price under 10% or over 1,000% of its plan's standing price is refused whole: `422 RATE_OUT_OF_BAND`, nothing written. Check input on the screen. Do not work around it by splitting or retrying.
- Dates are `YYYY-MM-DD` calendar days in the hotel's timezone (`GET /property`). Keep them as strings; do date arithmetic in UTC. Never build one from a local `Date`, never shift one by an offset. `dateFrom` and `dateTo` are both included.
- Every write carries `x-idempotency-key` (10 to 64 characters of `[A-Za-z0-9_-]`; a UUID fits): a new one per write, the same one on its retries. After a 4xx other than 429, the corrected request takes a new one.
- A write answers `202` with a `batchId`: the values are in ZimmerStack's record and travel to the channels on their own (availability in seconds, prices and rules within a minute or two, longer under load). Say "saved, syncing", never "live on Booking.com".
- A `202` may still list `rejected` groups and `warnings`. Show them; everything else in the request landed.
- Do not build "sync everything", "force push" or "reset calendar" buttons.

### 4. When ZimmerStack says stop, stop

- `403 WRITES_SUSPENDED`, `503 WRITES_FROZEN`, or `429` with `data.scope` `shield-pause`: stop writing, keep the person's changes, show the message. Do not rotate keys, change IP addresses, split requests or add retries to get around it. A write that only closes inventory (a lower count, `stopSell`) is still accepted while paused, so a hotel never oversells.
- `401`: the key is wrong, revoked or expired. Stop at once: 20 failed attempts in a minute lock the IP address out, a good key included.
- `403 IP_NOT_ALLOWED`: the server's address is not on the key's allowlist. The hotel's owner adds it.
- `403 SCOPE_MISSING`: `data.details.needed` names the scope to ask the owner for.

### 5. Webhooks: OTA bookings arriving

- Verify every delivery before trusting it: the Standard Webhooks headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`), HMAC-SHA256 over `id.timestamp.rawBody` with the endpoint's secret, a constant-time compare, and no timestamp older than five minutes. Verify the RAW body, before any JSON parsing.
- Answer 2xx within 10 seconds and do the work afterwards. Deliveries are at-least-once: ignore an event `id` you have already processed.
- The endpoint's secret is a secret like the key.
- Book money from `finance`, reading `finance.amountBasis` first: `amounts.total` is the guest's price on some OTAs and the OTA's payout on others. `finance.netPayoutAmount` is before the OTA's own deductions, never the bank amount.
- Match a booking you already hold on `channel.otaName` with `channel.otaReservationCode`. Missed deliveries are recovered from `GET /channel-bookings`, never by guessing.

### 6. Website bookings: apply them before you push room counts

- **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.

## Recipe: the 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.

Working TypeScript for all of it (a client that paces itself and retries correctly, the grid read and write, the range folding, a minimal screen) is at https://docs.zimmerstack.com/rate-grid and inside https://docs.zimmerstack.com/llms-full.txt. Copy it; do not rewrite it from memory.

## Recipe: 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.

## Before you tell the person it is done

- Search the built client bundle and the repository history for `zsk_`: no match.
- `.env` is ignored by git; `.env.example` names `ZIMMERSTACK_CONNECT_KEY` with no value.
- Tests and scripts run on a `zsk_test_` key or on mocks.
- Every write sends ranges, carries an idempotency key, and runs one at a time.
- No timer, loop or page load writes to ZimmerStack. No polling faster than every 15 seconds.
- `429` waits for `Retry-After`; other `4xx` are shown to the person, not retried.
- Prices are converted between major and minor units in one place, and dates never pass through a local `Date`.
- A channel's modifier is set only from a person's own save, and the re-send only from a person's own button.
- A PMS that pushes room counts applies every website booking (`direct.booking.*`, `GET /direct-bookings`) to its own calendar before each push.
- The screen says what was saved and what was refused, in the API's own words.
