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
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 (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: 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 });
}// 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:
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 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 API's ruleThe key stays on a serverWhat 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 minuteWhat 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 burstWhat 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 timeWhat 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 twiceWhat 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 sizeWhat 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 retriedWhat 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 hotelWhat 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.
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 to | Call |
|---|---|
| Know the hotel and the key | zs.property.get() · zs.properties.list() · zs.forProperty(id) |
| Room types and rate plans | zs.catalog.get() · upsertRoomTypes() · upsertRatePlans() · deleteRoomType() · deleteRatePlan() |
| Draw and save a grid | zs.grid.load(from, to) · zs.grid.save(edits) |
| Read or set one resource | zs.availability / zs.rates / zs.restrictions .get({ from, to }) · .set(updates) |
| See it reach the channels | zs.batches.wait(batchId) · zs.batches.get(batchId) · zs.sync.get() |
| Price a channel differently | zs.channels.list() · zs.channels.setModifier(channelId, steps) · zs.rates.resend() · channelPrice(rate, steps) |
| Hand over your own bookings | zs.bookings.create() · .get() · .list() · .cancel() |
| Receive OTA bookings | verifyWebhook(rawBody, headers, secret) · zs.channelBookings.all({ since }) |
| Pretend an OTA booked | zs.sandbox.bookings.create() · .modify() · .cancel() |
| Anything else in the contract | zs.request("GET /sync") |
- You want toKnow the hotel and the keyCallzs.property.get() · zs.properties.list() · zs.forProperty(id)
- You want toRoom types and rate plansCallzs.catalog.get() · upsertRoomTypes() · upsertRatePlans() · deleteRoomType() · deleteRatePlan()
- You want toDraw and save a gridCallzs.grid.load(from, to) · zs.grid.save(edits)
- You want toRead or set one resourceCallzs.availability / zs.rates / zs.restrictions .get({ from, to }) · .set(updates)
- You want toSee it reach the channelsCallzs.batches.wait(batchId) · zs.batches.get(batchId) · zs.sync.get()
- You want toPrice a channel differentlyCallzs.channels.list() · zs.channels.setModifier(channelId, steps) · zs.rates.resend() · channelPrice(rate, steps)
- You want toHand over your own bookingsCallzs.bookings.create() · .get() · .list() · .cancel()
- You want toReceive OTA bookingsCallverifyWebhook(rawBody, headers, secret) · zs.channelBookings.all({ since })
- You want toPretend an OTA bookedCallzs.sandbox.bookings.create() · .modify() · .cancel()
- You want toAnything else in the contractCallzs.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 }).
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(andZIMMERSTACK_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 readzs.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 callsawait connection()inside a<Suspense>boundary, notexport const dynamic.
When the API says no
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.
# 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.mdBuild 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.
| Tool | What the agent gets |
|---|---|
| zimmerstack_rules | The rules for building on the API: the key, pacing, money and dates, a closing checklist. |
| zimmerstack_reference | Any operation, type, limit or error code, with its sample and the package's call for it. |
| zimmerstack_sandbox_read | One read on your sandbox: real ids and real shapes. |
| zimmerstack_sandbox_write | One write on your sandbox, to try a body before writing the code that sends it. |
- Toolzimmerstack_rulesWhat the agent getsThe rules for building on the API: the key, pacing, money and dates, a closing checklist.
- Toolzimmerstack_referenceWhat the agent getsAny operation, type, limit or error code, with its sample and the package's call for it.
- Toolzimmerstack_sandbox_readWhat the agent getsOne read on your sandbox: real ids and real shapes.
- Toolzimmerstack_sandbox_writeWhat the agent getsOne write on your sandbox, to try a body before writing the code that sends it.
# Claude Code
claude mcp add zimmerstack -- npx -y @zimmerstack/connect mcpNot 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.