Skip to content

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

A sample rate grid: rooms left to sell per room type and a price per rate plan, for seven nights
Room type / rate planThu12 NovFri13 NovSat14 NovSun15 NovMon16 NovTue17 NovWed18 Nov
Deluxe Garden Roomrooms to sell · roomTypeId 4125314555
Bed and breakfastratePlanId 9014,5005,2005,200stop sell4,5004,5004,5004,500
Family Suiterooms to sell · roomTypeId 4133102333
Room only, non-refundableratePlanId 9025,9006,6006,6005,9005,9005,9005,900
The shape of the screen, with illustrative numbers in INR. Rows come from 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 scopes ari:read and ari: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. 1

    Read the rows

    GET /catalog lists 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. 2

    Read the cells

    Three reads cover every row for the whole window: GET /availability, GET /rates and GET /restrictions, each with from and to. Draw 14 to 60 nights and read the next window when the person scrolls.
  3. 3

    Let the person edit

    Keep one pending change per cell on the screen. Send nothing while they type.
  4. 4

    Save in ranges

    Fold the changes into ranges (consecutive nights of one row with the same value are one update) and send one PUT per kind of change, one after another.
  5. 5

    Show that it landed

    A write answers 202 with a batchId: saved in our record, on its way to the channels. Ask GET /batches/{batchId} until it says landed.
  6. 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

  • PartThe rows
    RouteGET /catalog
    Gives youRoom types and rate plans, with their ids, names, meal plan and the property's currency.
  • PartRooms to sell
    RouteGET /availability
    Gives youOne count per room type per night.
  • PartPrices
    RouteGET /rates
    Gives youOne price per rate plan per night, in minor units: divide by 100 to show it.
  • PartStay rules
    RouteGET /restrictions
    Gives youPer rate plan per night: stop sell, closed to arrival, closed to departure, minimum and maximum stay.
the four reads
# 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"
what the three cell reads answer (data)
// 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 }] }
  • from and to are 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.

PUT /rates
{
  "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 dateFrom and dateTo; every Friday and Saturday of a season is one update with days. 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: 4500 with the property's currency; read rateMinor: 450000. Convert in one place.
  • Close a night with a rule, not a price. stopSell: true on PUT /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-key per Save, the same one when you retry it, so a request that timed out can never land twice.

Show that it landed

202 Accepted (data)
{
  "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:

  • When202 arrived
    ShowSaved, syncing to the channels
    BecauseThe record holds it; the push is on its way.
  • Whenstatus: landed
    ShowSynced
    BecauseNothing of this write is still waiting.
  • Whenstatus: failed
    ShowNot synced, with lastError
    BecauseThe 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.

zimmerstack.ts · the client
/**
 * 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:

  • Code429 RATE_LIMITED
    MeansA 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_BAND
    MeansA 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 HORIZON
    MeansA night in the past or more than 365 days ahead.
    The screen shouldNot offer those nights for editing.
  • Code400 UNKNOWN_RATE_PLAN
    MeansAn 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_CELLS
    MeansOne request named too many cells.
    The screen shouldSplit it; the sample's chunk() does.
  • Code403 WRITES_SUSPENDED · 503 WRITES_FROZEN
    MeansZimmerStack 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.