Skip to content

Start

Node package

The Connect API from your server in one install. Every request and answer is typed from the API's own contract, and the rules that keep a hotel's prices safe (pacing, retries, idempotency, where the key may live) are kept by the package, not left to you.

Install

terminal
npm install @zimmerstack/connect
Runs on
Node 20 or newer, on a server. It refuses to start in a browser or a mobile app: your frontend calls your server, and your server calls ZimmerStack.
Depends on
Nothing. One package, no transitive installs.
Module format
ES modules and CommonJS, each with its own types. It loads the same under Next.js, Express, a plain script and Jest.
The key
Read from the environment variable ZIMMERSTACK_CONNECT_KEY. Never passed in code you commit.
.env
# .env  (git-ignored; the key never leaves your server)
ZIMMERSTACK_CONNECT_KEY=zsk_test_...

# .env.example  (committed: the name, never a value)
ZIMMERSTACK_CONNECT_KEY=

Start from a working app

A small Next.js app on this package: the next fortnight of rooms and prices, a price change, pretend OTA bookings and the signed webhook. Deploy it with your test key and change it from there.

Your app has no server?

A page made with Vite, Lovable, Bolt or plain HTML runs in the visitor's browser, and so does anything in it. The key can change a hotel's prices on every channel, so it must never reach a browser. What you will see if it does: the package stops with a blank page and, in the browser's console, ZimmerStackUsageError: … runs on a server only; a plain fetch to the API from a browser fails with Failed to fetch. Both are on purpose. Never put the key in a variable your bundler sends to the browser (VITE_, NEXT_PUBLIC_, REACT_APP_, EXPO_PUBLIC_): it is in every visitor's copy of your site. If you already did, revoke that key and make a new one.

The fix is one small file on a server that holds the key; your page calls it. Pick the one that matches your host:

app/api/hotel/route.ts
// app/api/hotel/route.ts: your page fetches /api/hotel; only this file sees the key.
import { ZimmerStack } from "@zimmerstack/connect";

const zs = new ZimmerStack(); // reads ZIMMERSTACK_CONNECT_KEY on the server

export async function GET() {
  const property = await zs.property.get();
  return Response.json({ name: property.name, currency: property.currency });
}
your page
// In the browser: call YOUR route. No key, no package.
const hotel = await fetch("/api/hotel").then((r) => r.json());

The first calls

With a sandbox key (zsk_test_) nothing you send reaches a channel. A software company makes one in the partner portal under Developers (not a partner yet? sign up free); a hotel's own developer gets one from the owner (Admin → Developers → API keys). Read the property, load a fortnight of the grid, change one price and watch it land:

scripts/first-calls.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<void> {
  // 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
  }
}

What it keeps so you do not have to

  • The API's ruleThe key stays on a server
    What the package doesRefuses 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.
  • The API's ruleBudgets per minute
    What the package doesReads the RateLimit header on every answer and waits before a budget runs out, instead of earning a 429.
  • The API's ruleWrites are never a burst
    What the package doesSends writes one at a time, in the order they were made. At most four reads at once.
  • The API's ruleRetry only what passes with time
    What the package doesRetries 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.
  • The API's ruleA retry must not write twice
    What the package doesGives 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.
  • The API's ruleA request has a size
    What the package doesSplits a write at 1,000 updates or 5,000 cells, and folds single nights into ranges (grid.save).
  • The API's ruleA refused key is not retried
    What the package doesAfter API_KEY_INVALID, API_KEY_REVOKED or API_KEY_EXPIRED it stops calling, so an address is never locked out by a loop.
  • The API's ruleA test must not touch a real hotel
    What the package doesRefuses to write with a zsk_live_ key under a test runner (NODE_ENV=test, Vitest, Jest, node --test).

What it cannot decide for you is when to write. Send what a person changed, when they saved it; never on a timer, on page load or “to be safe”. Rate limits has the budgets and what counts against them.

In a Next.js app

Three route handlers on top of that one client: the rate grid, a different price per channel, and bookings arriving by webhook. These files are compiled and run against the built package every time it changes, so they are the code that works, not a sketch of it.

app/api/grid/route.ts · the rate grid
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<Response> {
  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<Response> {
  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);
  }
}

The screens these routes serve are yours. Build a rate grid explains what each cell means and how a save travels; Prices per channel explains a modifier and when it takes effect.

Everything it covers

  • You want toKnow the hotel and the key
    Callzs.property.get() · zs.properties.list() · zs.forProperty(id)
  • You want toRoom types and rate plans
    Callzs.catalog.get() · upsertRoomTypes() · upsertRatePlans() · deleteRoomType() · deleteRatePlan()
  • You want toDraw and save a grid
    Callzs.grid.load(from, to) · zs.grid.save(edits)
  • You want toRead or set one resource
    Callzs.availability / zs.rates / zs.restrictions .get({ from, to }) · .set(updates)
  • You want toSee it reach the channels
    Callzs.batches.wait(batchId) · zs.batches.get(batchId) · zs.sync.get()
  • You want toPrice a channel differently
    Callzs.channels.list() · zs.channels.setModifier(channelId, steps) · zs.rates.resend() · channelPrice(rate, steps)
  • You want toHand over your own bookings
    Callzs.bookings.create() · .get() · .list() · .cancel()
  • You want toReceive OTA bookings
    CallverifyWebhook(rawBody, headers, secret) · zs.channelBookings.all({ since })
  • You want toPretend an OTA booked
    Callzs.sandbox.bookings.create() · .modify() · .cancel()
  • You want toAnything else in the contract
    Callzs.request("GET /sync")

A software vendor's company key

A company key reaches many hotels, so every call names one. A test company key reaches your sandboxes; while you have one, the package finds it by itself, so the first calls above work unchanged. With several, name one; a live key never guesses. An app that serves one hotel can name it once: ZIMMERSTACK_PROPERTY_ID=61 in the environment, or new ZimmerStack({ propertyId: 61 }).

one client, many hotels
const { properties } = await zs().properties.list();   // the hotels this key may act on

for (const property of properties) {
  const hotel = zs().forProperty(property.id);         // the same client and pace, acting on one hotel
  const sync = await hotel.sync.get();
  console.log(property.name, sync.rates.dirtyCells);
}

Publishing your app

  • Put ZIMMERSTACK_CONNECT_KEY (and ZIMMERSTACK_WEBHOOK_SECRET) in your host's environment settings, marked secret; never in the repository.
  • A key's address allowlist takes your server's outgoing addresses. Vercel, Netlify and most serverless hosts have none fixed: leave the allowlist empty while you build, and before live either use a host or proxy with fixed outgoing addresses or keep it empty and rotate the key on any doubt.
  • A request handler answers within seconds on a serverless host: never zs.batches.wait() inside one. Show the batch id and read zs.sync.get() later.
  • Nothing survives between two calls of a serverless function: with no database yet, read bookings back with zs.channelBookings.list() rather than keeping what the webhook sent.
  • Next.js 16 with cacheComponents (the default for a new app): a page that reads the API calls await connection() inside a <Suspense> boundary, not export const dynamic.

When the API says no

a refusal
import { ZimmerStackError } from "@zimmerstack/connect";

try {
  await zs().rates.set(updates);
} catch (err) {
  if (!(err instanceof ZimmerStackError)) throw err;
  err.code;               // stable: RATE_OUT_OF_BAND, SCOPE_MISSING, RATE_LIMITED, …  branch on this
  err.message;            // a sentence for the person in front of the screen: show it
  err.retryAfterSeconds;  // when a budget refused: when to try again
  err.retryable;          // false = a verdict on the request. Fix it; never send it again.
}

The package has already waited and retried where that was worth it. Do not wrap its calls in a retry loop of your own. Every code is on Errors.

For your coding agent

The package carries a rules file written for the agent that builds on it: where the key lives, what the package already handles, when a write is allowed, and a closing checklist. It is generated from the same contract as this site.

terminal
# The package ships its own rules file. APPEND it where your agent reads rules
# (Next.js and other tools write their own AGENTS.md: never copy over it):
cat node_modules/@zimmerstack/connect/AGENTS.md >> AGENTS.md

# Claude Code reads CLAUDE.md; one line imports it:
printf '\n@AGENTS.md\n' >> CLAUDE.md

Build with an AI agent has the wider kit: the rules for the API itself and the whole reference in one file.

An MCP server, so the agent looks things up

The package also carries an MCP server. Connected to your coding agent, it lets the agent read the rules, look up any part of the API from the contract, and try a call on your sandbox before it writes the code that makes it.

  • Toolzimmerstack_rules
    What the agent getsThe rules for building on the API: the key, pacing, money and dates, a closing checklist.
  • Toolzimmerstack_reference
    What the agent getsAny operation, type, limit or error code, with its sample and the package's call for it.
  • Toolzimmerstack_sandbox_read
    What the agent getsOne read on your sandbox: real ids and real shapes.
  • Toolzimmerstack_sandbox_write
    What the agent getsOne write on your sandbox, to try a body before writing the code that sends it.
terminal
# Claude Code
claude mcp add zimmerstack -- npx -y @zimmerstack/connect mcp

Not on Node?

The API is plain HTTPS and JSON. Build a rate grid prints a small client you can port to any language (it shows the pacing and retry rules in ninety lines), and the OpenAPI contract and Postman collection generate a client for the rest.

Routes, samples, limits and codes on this page come from the API's public contract, read live, Tue, 17 Nov 2026 02:54:26 UTC.