Guides
Build a rate grid
The screen every hotel asks for first: room types and rate plans down the side, nights across the top, prices and room counts you can change. Four reads draw it. One write per kind of change saves it.
What you are building
| Room type / rate plan | Thu12 Nov | Fri13 Nov | Sat14 Nov | Sun15 Nov | Mon16 Nov | Tue17 Nov | Wed18 Nov |
|---|---|---|---|---|---|---|---|
| Deluxe Garden Roomrooms to sell · roomTypeId 412 | 5 | 3 | 1 | 4 | 5 | 5 | 5 |
| Bed and breakfastratePlanId 901 | 4,500 | 5,200 | 5,200stop sell | 4,500 | 4,500 | 4,500 | 4,500 |
| Family Suiterooms to sell · roomTypeId 413 | 3 | 1 | 0 | 2 | 3 | 3 | 3 |
| Room only, non-refundableratePlanId 902 | 5,900 | 6,600 | 6,600 | 5,900 | 5,900 | 5,900 | 5,900 |
GET /catalog; the top line of each group from GET /availability; prices from GET /rates; the closed Saturday from GET /restrictions.- Rows
- Each room type, then the rate plans that sell it. Both come from GET /catalog, with the numeric ids every other route names.
- Rooms to sell
- Belong to the room type: one count per night, however many plans sell that room.
- Price and stay rules
- Belong to the rate plan: one price per night, and the rules for that night (stop sell, closed to arrival or departure, minimum and maximum stay).
- One grid per hotel
- A price is sent to every channel its rate plan is mapped to. Selling at different prices on different OTAs is covered below.
Before you start
- A sandbox key (
zsk_test_…) with the scopesari:readandari:write. The sandbox is a copy of a real property that no channel sees: build the whole screen there, then swap the key. - A server of your own. Your screen calls your server, and your server calls ZimmerStack. The Quickstart covers the first request.
The order of work
- 1
Read the rows
GET /cataloglists the room types and, for each rate plan, the room type it sells. It changes when the owner adds a room type or a plan, not while a grid is open: read it once and keep it for ten minutes. - 2
Read the cells
Three reads cover every row for the whole window:GET /availability,GET /ratesandGET /restrictions, each withfromandto. Draw 14 to 60 nights and read the next window when the person scrolls. - 3
Let the person edit
Keep one pending change per cell on the screen. Send nothing while they type. - 4
Save in ranges
Fold the changes into ranges (consecutive nights of one row with the same value are one update) and send onePUTper kind of change, one after another. - 5
Show that it landed
A write answers202with abatchId: saved in our record, on its way to the channels. AskGET /batches/{batchId}until it sayslanded. - 6
Keep it fresh
Read the window again after a save, when a booking webhook names those nights, and when the person asks. Never on a timer.
Read it: four requests
| Part | Route | Gives you |
|---|---|---|
| The rows | GET /catalog | Room types and rate plans, with their ids, names, meal plan and the property's currency. |
| Rooms to sell | GET /availability | One count per room type per night. |
| Prices | GET /rates | One price per rate plan per night, in minor units: divide by 100 to show it. |
| Stay rules | GET /restrictions | Per rate plan per night: stop sell, closed to arrival, closed to departure, minimum and maximum stay. |
- PartThe rowsRouteGET /catalogGives youRoom types and rate plans, with their ids, names, meal plan and the property's currency.
- PartRooms to sellRouteGET /availabilityGives youOne count per room type per night.
- PartPricesRouteGET /ratesGives youOne price per rate plan per night, in minor units: divide by 100 to show it.
- PartStay rulesRouteGET /restrictionsGives youPer rate plan per night: stop sell, closed to arrival, closed to departure, minimum and maximum stay.
# Rows: once, then keep it for ten minutes
curl "https://api.zimmerstack.com/api/v1/connect-api/v1/catalog" -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY"
# Cells: three reads cover every row for the whole window
curl "https://api.zimmerstack.com/api/v1/connect-api/v1/availability?from=2026-11-12&to=2026-12-11" -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY"
curl "https://api.zimmerstack.com/api/v1/connect-api/v1/rates?from=2026-11-12&to=2026-12-11" -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY"
curl "https://api.zimmerstack.com/api/v1/connect-api/v1/restrictions?from=2026-11-12&to=2026-12-11" -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY"// GET /availability one cell per room type per night
{ "from": "2026-11-12", "to": "2026-12-11",
"cells": [{ "roomTypeId": 412, "date": "2026-11-12", "available": 5 }] }
// GET /rates one cell per rate plan per night, in MINOR units (450000 = 4,500.00)
{ "from": "2026-11-12", "to": "2026-12-11", "currency": "INR",
"cells": [{ "ratePlanId": 901, "date": "2026-11-12", "rateMinor": 450000, "source": "MANUAL" }] }
// GET /restrictions one cell per rate plan per night; null = no rule set
{ "from": "2026-11-12", "to": "2026-12-11",
"cells": [{ "ratePlanId": 901, "date": "2026-11-14", "stopSell": true, "closedToArrival": null,
"closedToDeparture": null, "minStayArrival": 2, "minStayThrough": null, "maxStay": null }] }fromandtoare both included, and default to today and today + 30 days. One read may span up to 500 days; a screen never needs that many at once.- Reads are answered from our record, never from the channel manager, so they are fast. They still spend your request budget (120 a minute per key): read a window when it comes into view, not every row or every night on its own.
- Dates are calendar days in the hotel's own timezone (
GET /property). Keep them as the strings you were given; a date that passes through the browser's local time can land on the wrong night.
Write it: ranges, one request per kind
Three routes, one shape: an updates array of ranges. Values are absolute (a room count is the count, not a change to it), the last update in a request wins for a night, and a cell that already holds the value costs nothing.
{
"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"
}
]
}- Ranges, not nights. Thirty nights at one price are one update with
dateFromanddateTo; every Friday and Saturday of a season is one update withdays. One request carries up to 1,000 updates and 5,000 cells (a cell is one row on one night). - Only what changed. Send the cells the person edited, when they press Save. Re-sending the calendar on a timer or on every page load spends your budget and gets an integration paused.
- One write at a time. A key has 30 writes a minute and a hotel 60 across all its keys. A Save is at most three requests; send them one after another.
- Prices go up in major units and come back in minor units. Send
rate: 4500with the property'scurrency; readrateMinor: 450000. Convert in one place. - Close a night with a rule, not a price.
stopSell: trueonPUT /restrictions. A price of 0 is refused. So is a price under 10% or over 1,000% of the plan's standing price (price band): check what the person typed before you send it. - Every write carries an idempotency key. A fresh
x-idempotency-keyper Save, the same one when you retry it, so a request that timed out can never land twice.
Show that it landed
{
"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"
}A 202 means the values are in our record. Room counts reach the channels in seconds and prices and rules within a minute or two, longer when much is changing. Say so on the screen, in three states:
| When | Show | Because |
|---|---|---|
| 202 arrived | Saved, syncing to the channels | The record holds it; the push is on its way. |
status: landed | Synced | Nothing of this write is still waiting. |
status: failed | Not synced, with lastError | The channel manager refused a value. Correct that night and save again. |
- When202 arrivedShowSaved, syncing to the channelsBecauseThe record holds it; the push is on its way.
- When
status: landedShowSyncedBecauseNothing of this write is still waiting. - When
status: failedShowNot synced, with lastErrorBecauseThe channel manager refused a value. Correct that night and save again.
Ask GET /batches/{batchId} no more often than every 15 seconds and stop after about five minutes; GET /sync answers for the whole property at any time. A 202 may also list rejected groups (a plan whose policy refused the change) and warnings: show them beside the rows they name. Everything else in the request was saved.
Keep it fresh
- After a save, read the window once more: the screen then shows what the record holds.
- When an OTA booking arrives, the webhook names its nights and room types. Read those nights again; a room count went down. So does a booking from the hotel's own website (
direct.booking.created: Bookings from the hotel's own website). - When the person presses Refresh or returns to the tab after a while.
- Not on a timer. A grid that reloads every few seconds for every open tab is how an integration uses up its budget.
The code
Four files, no dependencies, Node 20 or newer. The first three run on your server; the fourth is the screen. They are checked against the contract whenever this site changes: every body they send passes the schema the server validates with.
/**
* 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<string, string | number | undefined>;
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<string, unknown>;
}
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<T>(path: string, opts: ZsOptions = {}): Promise<T> {
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<string, string> = { 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
}
}
- zimmerstack.ts
- Adds the key, unwraps the answer, slows down when the RateLimit header says the budget is nearly used, waits out a 429 and retries a fault on our side with the same idempotency key. Never retries another refusal.
- grid.ts
- loadGrid builds the rows from the catalog and fills them from the three reads. saveGrid folds single-night edits into ranges and sends one write per kind. waitForBatch asks whether it landed, no faster than every 15 seconds.
- route.ts
- Two endpoints on your own server, behind your own sign-in: read a window, save the changes. Written as a Next.js route handler; the two functions fit any framework.
- RateGrid.tsx
- A table with editable prices that saves only the cells that changed and reads the grid back. Deliberately plain: restyle it, then add room counts and rules the same way.
When a write is refused
A refusal carries a stable data.code and a sentence for the person. Show the sentence beside what caused it, keep what they typed, and never resend a refusal unchanged. The ones a grid meets:
| Code | Means | The screen should |
|---|---|---|
| 429 RATE_LIMITED | A budget is used up; Retry-After says for how long. | Wait that long and send the same request again. If it is more than a couple of minutes, keep the changes and say when to try again. |
| 422 RATE_OUT_OF_BAND | A price far from the plan's standing price. Nothing was written. | Point at the price and ask the person to check it. |
| 400 HORIZON | A night in the past or more than 365 days ahead. | Not offer those nights for editing. |
| 400 UNKNOWN_RATE_PLAN | An id that is not on this property (the owner removed the plan). | Read the catalog again and redraw the rows. |
| 400 TOO_MANY_CELLS | One request named too many cells. | Split it; the sample's chunk() does. |
| 403 WRITES_SUSPENDED · 503 WRITES_FROZEN | ZimmerStack has stopped this integration's writes, or everyone's for a moment. | Keep the changes, show the message, stop sending. Reads still work. |
- Code429 RATE_LIMITEDMeansA budget is used up; Retry-After says for how long.The screen shouldWait that long and send the same request again. If it is more than a couple of minutes, keep the changes and say when to try again.
- Code422 RATE_OUT_OF_BANDMeansA price far from the plan's standing price. Nothing was written.The screen shouldPoint at the price and ask the person to check it.
- Code400 HORIZONMeansA night in the past or more than 365 days ahead.The screen shouldNot offer those nights for editing.
- Code400 UNKNOWN_RATE_PLANMeansAn id that is not on this property (the owner removed the plan).The screen shouldRead the catalog again and redraw the rows.
- Code400 TOO_MANY_CELLSMeansOne request named too many cells.The screen shouldSplit it; the sample's chunk() does.
- Code403 WRITES_SUSPENDED · 503 WRITES_FROZENMeansZimmerStack has stopped this integration's writes, or everyone's for a moment.The screen shouldKeep the changes, show the message, stop sending. Reads still work.
Every code and its meaning is on Errors; every budget on Rate limits.
Prices that differ per OTA
There is one grid per hotel. A rate plan has one price for a night, and that price goes to every channel the plan is mapped to. What differs per channel is the channel's modifier: a few steps (raise or lower, by a percentage or a fixed amount) applied to every price sent to that channel. GET /channels shows each channel's steps, PUT /channels/{channelId}/modifier sets them, and POST /rates/resend sends the prices again so nights already on the channel pick them up.
- In your grid
- Keep the base price in the cell, and show what each channel is sent beside it: the price with that channel's steps applied in order.
- 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.
- One OTA, its own nights
- When one OTA needs a price of its own on particular nights, give it a rate plan of its own instead: one more row in this grid.
Routes, samples, limits and codes on this page come from the API's public contract, from the checked-in snapshot (the live contract was unreachable when this page rendered), Tue, 17 Nov 2026 03:05:45 UTC.