Start
Glossary
The words these pages use that a newcomer may not know, one short paragraph each. Elsewhere on this site, a word with a dotted underline links to its entry here.
The words, A to Z:
- Absolute room counts
- ARI
- At-least-once
- Batch
- Company key
- The drain (on its way to the channels)
- Enrol, enrolment
- Hotel key
- Idempotency key
- Modifier
- OTA, channel, channel manager
- Rate plan
- Room type
- Sandbox
- Scope
- Source of truth (our record)
- Stay rules (restrictions)
- Test key and live key
- Vendor code
- Webhook
- The X-ZS-Property header
Keys and access
Scope
A permission a key holds, named like ari:write or bookings:read. Every route needs exactly one scope, and a key without it is refused with 403 SCOPE_MISSING. A key's scopes are chosen when it is made and can be changed later without a new key.
For example: A PMS that only sends prices, room counts and stay rules needs ari:read and ari:write, nothing else.
More: Every scope
Hotel key
A key that belongs to one hotel and acts only for it. The hotel's owner makes it in Admin → Developers. The key is the hotel, so a request never says which hotel it is for.
More: Which key are you holding?
Company key
A key that belongs to a software company (for example a PMS that serves many hotels) and reaches every hotel the company may act for. You make it in the partner portal, under Developers. Every request names its hotel in the X-ZS-Property header; GET /properties lists the hotels the key reaches.
More: Hotel key and company key compared
Test key and live key
A key's first letters say where it works. A zsk_test_ key works only on a sandbox, so nothing it sends reaches a real hotel or an OTA. A zsk_live_ key works only on real hotels. A key used in the wrong place is refused with 409 PROPERTY_UNAVAILABLE, so a test key pasted into production fails on the first request.
More: A key's life
Sandbox
A pretend hotel that no OTA ever sees, for building and testing. Every route answers as on a real hotel, and the sandbox can pretend that an OTA booked, changed or cancelled, sending you the real webhooks. A software partner's sandbox is made at sign-up, in the currency and time zone of the partner's own country; a hotel's owner can make one as a copy of a real hotel.
More: Sandbox
The X-ZS-Property header
The header that tells a company key which hotel a request is for, by the hotel's id from GET /properties. Without it a company key's request is refused with 400 PROPERTY_REQUIRED; a hotel key never needs it. With the Node package you do not write the header yourself: zs.forProperty(id) sets it on every call, and so does ZIMMERSTACK_PROPERTY_ID in your environment, for an app that serves one hotel.
For example: X-ZS-Property: 61 on every request about hotel 61.
More: A company key in the Node package
Vendor code
A short code that names your company to hotels. You find it in the partner portal, under Developers, and give it to a hotel that already runs ZimmerStack. Its owner enters it (Integrations → Software vendors) to let your company key act for that hotel, and can take that back at any time.
Enrol, enrolment
Adding a hotel to your company yourself, in the partner portal: usually a hotel moving to ZimmerStack with you. The hotel works at once and your live company key reaches it; ZimmerStack confirms its billing within one working day. The other way your key reaches a hotel is its owner entering your vendor code.
More: Move a hotel to ZimmerStack
A hotel's calendar
OTA, channel, channel manager
An OTA (online travel agency) is a site that sells hotel rooms: Booking.com, Expedia, Airbnb, Agoda, MakeMyTrip and the rest. Each one a hotel sells on is a channel. A channel manager keeps them all in step: it sends every channel the hotel's room counts, prices and stay rules, and brings their bookings back. ZimmerStack is the hotel's channel manager; this API is how your software talks to it.
Room type
A kind of room the hotel sells, such as a Deluxe Double. A guest books a room type, not a room number, and rooms of one type are counted together. Each room type has a numeric id from GET /catalog, which every request about it uses.
For example: Deluxe Garden Room, id 412.
More: The ids every write names
Rate plan
One way of selling a room type, with its own price for every night: room only, with breakfast, non-refundable. Each rate plan belongs to exactly one room type and has its own id from GET /catalog.
For example: Deluxe Garden Room · Bed and breakfast, id 901.
More: Meal plans: one rate plan per board basis
ARI
Short for availability, rates and inventory: the industry's name for what a channel manager sends to the OTAs. In this API it is three things for every night: availability (how many rooms of a type are left to sell), rates (each rate plan's price) and restrictions (the stay rules). The scopes ari:read and ari:write read and set all three.
For example: Deluxe Garden Room on 24 December: 3 rooms left, 120.00 a night on Bed and breakfast, at least 2 nights.
More: Channel manager
Absolute room counts
You send how many rooms are left, never how many to add or take away. If 3 Deluxe rooms are free on a night, send 3, whatever was there before. Sending the same number again changes nothing and costs nothing, and a message that went missing is put right by the next one.
For example: A walk-in takes one of 4 free rooms: send 3, not -1.
Stay rules (restrictions)
Rules on when a rate plan can be booked, set night by night with PUT /restrictions: stop-sell (stopSell: not sold that night), minimum stay (minStayArrival for a stay that arrives that night, minStayThrough for one that covers it), maximum stay (maxStay), closed to arrival (closedToArrival: no stay may start that day) and closed to departure (closedToDeparture: no stay may end that day).
For example: { "ratePlanId": 901, "dateFrom": "2026-12-31", "dateTo": "2026-12-31", "stopSell": true } closes New Year's Eve on that plan.
More: Build a rate grid
Modifier
A channel's own adjustment to every price sent to it, so one OTA can sell higher or lower than the others. It is a short list of steps, such as add 18% then take 200 off. You read and set it per channel. It applies to prices sent after the change, so send the prices again (POST /rates/resend) for nights already on the channel.
For example: A night priced 100.00, Booking.com's modifier +10%: Booking.com is sent 110.00, every other channel 100.00.
More: Prices per channel
How a change travels
Source of truth (our record)
The one place a hotel's prices, room counts and stay rules are kept: ZimmerStack's own record. Your writes land there first, the reads (GET /availability, GET /rates, GET /restrictions) answer from it, and only what is in it is sent to the OTAs. A hotel must have its rates and availability set as the source of truth here before channel-manager writes are taken (409 ARI_NOT_AUTHORITATIVE otherwise); a hotel you enrol starts that way.
Batch
One write, followed on its way to the channels. A write answers 202 with a batchId; GET /batches/{batchId} says whether it has landed, is still pending or failed. GET /sync says the same for the whole hotel. Ask no more often than every 15 seconds.
For example: 202 { "batchId": "…", "acceptedCells": 30 }, then the batch reads landed within a minute.
More: What a write answers
The drain (on its way to the channels)
The part of ZimmerStack that sends what changed in our record to every connected OTA, at the pace the channel manager allows. A write answers as soon as it is in our record; "on its way to the channels" means the drain has it and will send it: room counts usually in seconds, prices and stay rules within a minute or two, longer under load. A booking's new room counts go out the same way.
Idempotency key
A unique value you send with a write, in the x-idempotency-key header (10 to 64 letters, digits, _ or -), so that sending the same write twice, after a timeout for example, does it once: the repeat gets the first answer back instead of being done again. Use a new value for every new write; the same value with a different body is refused (409 IDEMPOTENCY_KEY_REUSED). A booking has one of its own: externalReference, your reservation id.
For example: x-idempotency-key: 3f1c9a2e-…, made fresh for each save with crypto.randomUUID().
More: Idempotency
Bookings coming back
Webhook
A message we send to your server when something happens, so you do not have to keep asking. Here, each OTA booking, change and cancellation is sent as an HTTPS POST to the address you register, signed with a secret only you and we hold, so you can check that it came from us.
For example: channel.booking.created, sent seconds after an OTA booking arrives.
More: Webhooks
At-least-once
A promise that every webhook arrives, but not that it arrives only once: a delivery we cannot be sure you received is sent again. Keep the event ids you have handled and ignore a repeat. Deliveries are usually in order, but for one booking the event with the later occurredAt wins.
More: When your server is down