Skip to content

Guides

Bookings from the hotel's own website

A hotel that keeps its own PMS and also sells on its own website through our booking engine: how those bookings reach your PMS, by webhook and by a read, and the one rule that keeps a sold room from going back on sale.

Who this is for

You build or run a hotel's PMS, and the hotel keeps it (it is not the ZimmerStack PMS). The hotel uses ZimmerStack's channel manager to sell on the OTAs and its booking engine to sell on its own website. A guest who books on that website never passes through an OTA, so without this your PMS would not hear of the booking, and its next push of room counts would put the room back on sale.

A hotel that sells on its own website through the ZimmerStack booking engine takes bookings no OTA sent. They reach a PMS under their own names: the webhooks direct.booking.created and direct.booking.cancelled, and GET /direct-bookings for the pull. The booking object is the one channel.booking.* carries, so one parser serves both families.

Website bookings only: the nightly and the hourly bookings of ZimmerStack's booking engine. A booking made at the front desk, or created by a key with POST /bookings, is not in this family: your own system made it, or the hotel's staff did.

The two events

They are a family of their own, not channel.booking.*, so the OTA events stay OTA only and an endpoint you registered before they existed hears nothing new until its owner ticks them. The envelope, the signature and the retries are the same as for every webhook: Webhooks.

  • Typedirect.booking.created
    WhenA guest confirmed a nightly or an hourly booking on the hotel's website.
  • Typedirect.booking.cancelled
    WhenThe guest cancelled on the booking page, or the hotel cancelled or deleted the booking in ZimmerStack. cancellation.reason says which.

created: a nightly or an hourly booking the guest confirmed. cancelled: the guest cancelled on the booking page, or the hotel cancelled or deleted the booking in ZimmerStack; cancellation.reason says which. There is no modified event: the booking engine never changes a booking's dates.

What the hotel changes on a website booking in ZimmerStack afterwards (other dates, one room of several cancelled, a no-show) sends no event. GET /direct-bookings lists that booking again, because since is on its last change: read it on a slow schedule too (once an hour is plenty), not only before a push. A cancelled event can also arrive for a booking whose created your endpoint never received (it ticked the types later): treat an unknown booking id as new and read it with GET /direct-bookings/{bookingId}.

direct.booking.created
{
  "id": "evt_9b1d7c52-3e0a-4f6b-8a14-6c2e5d0f7a31",
  "type": "direct.booking.created",
  "apiVersion": "2026-09-01",
  "occurredAt": "2026-10-30T12:00:00.000Z",
  "mode": "live",
  "property": {
    "id": 61,
    "name": "The Lantern House",
    "currency": "INR",
    "timezone": "Asia/Kolkata"
  },
  "data": {
    "booking": {
      "id": 100001,
      "reference": "TEST-WEB-4H7P9D",
      "status": "CONFIRMED",
      "stayStatus": "UPCOMING",
      "channel": {
        "otaName": "Website",
        "otaReservationCode": "TEST-WEB-4H7P9D",
        "source": "DIRECT_WEB",
        "sourceGroup": "DIRECT"
      },
      "stay": {
        "checkIn": "2026-11-13",
        "checkOut": "2026-11-15",
        "nights": 2,
        "dayUse": false
      },
      "guest": {
        "fullName": "Asha Verma",
        "firstName": "Asha",
        "lastName": "Verma",
        "phone": "+919876500000",
        "email": "asha.verma@example.com",
        "country": "IN",
        "language": "en"
      },
      "guestNotes": null,
      "occupancy": {
        "adults": 2,
        "children": 0
      },
      "rooms": [
        {
          "roomTypeId": 412,
          "ratePlanId": 901,
          "roomTypeName": "Deluxe Sea View",
          "mealPlan": "CP",
          "adults": 2,
          "children": 0,
          "checkIn": "2026-11-13",
          "checkOut": "2026-11-15",
          "nights": 2,
          "dayUse": false,
          "ratePerNight": 2700,
          "amount": 5400,
          "status": "UPCOMING"
        }
      ],
      "amounts": {
        "currency": "INR",
        "total": 5400,
        "paid": 1080,
        "balanceDue": 4320,
        "paymentCollect": "property"
      },
      "finance": null,
      "cancellation": null,
      "createdAt": "2026-10-30T12:00:00.000Z",
      "updatedAt": "2026-10-30T12:00:00.000Z"
    }
  },
  "changes": null,
  "previous": null
}

changes and previous are always null, and finance is null on every website booking. The booking object is the one the OTA events carry, with the property's numeric room-type ids from GET /catalog, so one parser serves both families.

Telling them from OTA bookings

channel.source is DIRECT_WEB, channel.sourceGroup is DIRECT and channel.otaName is "Website". finance is null (no OTA, no commission); amounts.paymentCollect is "property"; amounts.paid is what the guest paid online, amounts.balanceDue what the desk collects.

  • Event types
    OTA bookingchannel.booking.created · modified · cancelled
    Website bookingdirect.booking.created · cancelled
  • channel.otaName
    OTA bookingThe OTA: "Booking.com", "MakeMyTrip", …
    Website booking"Website"
  • channel.otaReservationCode
    OTA bookingThe OTA's reservation code
    Website bookingZimmerStack's own booking reference
  • channel.source · channel.sourceGroup
    OTA bookingCHANNEL_MANAGER · INDIRECT
    Website bookingDIRECT_WEB · DIRECT
  • finance
    OTA bookingThe OTA's money block (commission, payout), or null
    Website bookingnull: no OTA, no commission
  • amounts.paymentCollect
    OTA bookingota, property or unknown
    Website bookingproperty: the money is the hotel's, not an OTA's
  • amounts.paid
    OTA bookingThe amount recorded as paid so far
    Website bookingWhat the guest paid online; amounts.balanceDue is what the desk collects
  • changes · previous
    OTA bookingSet on a modified event
    Website bookingAlways null: there is no modified event
  • The pull
    OTA bookingGET /channel-bookings, scope channel-bookings:read
    Website bookingGET /direct-bookings, scope direct-bookings:read

The simplest test is the event type. If one function reads bookings from both places, read channel.source: DIRECT_WEB is the website.

Subscribing

An endpoint receives them only when it lists the two event types. An endpoint registered before they existed receives none until its owner ticks them.

  1. 1

    Register the endpoint

    As for any booking: Admin → Developers → Webhooks, Channels → Integrations, or the partner portal's Developers section for a company endpoint.
  2. 2

    Tick the two types

    direct.booking.created and direct.booking.cancelled. An endpoint receives these only when it lists the two types.
  3. 3

    An older endpoint needs its owner's tick

    An endpoint registered before these events existed receives none of them until its owner ticks them. Nothing you built before changes.
  4. 4

    Allow the read

    The key that reads them holds the scope direct-bookings:read. It is a scope of its own, in the channel-manager family: a software vendor's company key may hold it, and a key that holds channel-bookings:read does not read website guests unasked.

Apply it before you push room counts

A PMS that sends only what changed (a price, a stay rule) is not caught by this. A PMS that pushes absolute room counts (PUT /availability, Channel manager) is: the count it sends is the count the channels will hold. A website booking lowers that count before your PMS has heard of it.

A worked example: your PMS holds 5 Deluxe rooms

10:00
Your PMS holds 5 Deluxe rooms for 13 November. You pushed that count, so the channels hold 5.
10:20
A guest books one Deluxe room for that night on the hotel's website. The channels hold 4 at once; our record says 4.
10:21
direct.booking.created reaches your endpoint. If you do nothing, your PMS still shows 5.
10:30
Your PMS pushes its full calendar with PUT /availability, and the number for that night is 5, because it never heard of the booking. The channels hold 5 again: the room the guest took is on sale, and an OTA can sell it a second time.
Instead
Apply the booking to your own calendar first. Your PMS then holds 4, and the push says 4.

Two safeguards, both yours to keep. Apply direct.booking.created to your calendar before anything else the event triggers, and give a cancellation back (direct.booking.cancelled). And before a full push, read GET /direct-bookings since the last time you read it: it catches any booking a webhook has not delivered yet. ZimmerStack has no guard on the count: it does not refuse a push that is higher than what the website has sold.

The file below is both halves: the webhook route calls onWebhookEvent once the signature is checked, and the push calls catchUpWebsiteBookings before it works out the counts. It runs on your server, on top of the client of the rate-grid guide. MyCalendar is your PMS; the rest is what to call and in which order.

website.ts · apply a website booking, read before you push
/**
 * Bookings guests make on the hotel's own website, in your own PMS (the direct.booking.* family). Runs on your
 * server, on top of zimmerstack.ts. Two jobs:
 *
 *   1. onWebhookEvent: your webhook route calls it with an event whose signature you have already checked
 *      (the Webhooks page has the check). A website booking is put in your own calendar.
 *   2. pushRoomCounts: your PMS's push of absolute room counts. It reads GET /direct-bookings first, so every
 *      website booking is in your calendar before the counts are worked out. Without that, the push would put
 *      the room the guest took back on sale.
 *
 * The key needs the scope direct-bookings:read (and ari:write to push). The endpoint must list the two types
 * direct.booking.created and direct.booking.cancelled; an endpoint registered earlier hears neither until its
 * owner ticks them.
 */
import { zs } from "./zimmerstack";

/** The booking object. It is the one OTA bookings use; only the fields this file reads are named here. */
export interface WebsiteBooking {
  id: number;
  reference: string;
  status: "CONFIRMED" | "CANCELLED";
  /** Website bookings: otaName "Website", source "DIRECT_WEB", sourceGroup "DIRECT". */
  channel: { otaName: string; otaReservationCode: string; source: string; sourceGroup: string };
  stay: { checkIn: string; checkOut: string; nights: number; dayUse: boolean };
  /** One entry per room. */
  rooms: Array<{ roomTypeId: number; ratePlanId: number | null; checkIn: string; checkOut: string; status: string }>;
  /** Every change of the booking, created or cancelled, moves this forward. */
  updatedAt: string;
}

/** A verified delivery. `type` is a string: a newer API may add events. */
export interface WebhookEvent {
  id: string;
  type: string;
  data: { booking?: WebsiteBooking };
}

/** Yours to write: your own PMS. */
export interface MyCalendar {
  /**
   * Store the booking under its `id` with its status, and count its rooms against your own availability: a
   * CONFIRMED booking takes them, a CANCELLED one gives them back. Applying the same booking twice, or an
   * older version after a newer one, must change nothing: key it on `id` and ignore an older `updatedAt`.
   */
  setWebsiteBooking(booking: WebsiteBooking): Promise<void>;
  /** The updatedAt of the last website booking you applied, kept between runs; undefined before the first. */
  lastSeen(): Promise<string | undefined>;
  saveLastSeen(updatedAt: string): Promise<void>;
}

/** A website booking, not an OTA one. An OTA booking would name the OTA and say CHANNEL_MANAGER. */
export const isWebsiteBooking = (booking: WebsiteBooking) => booking.channel.source === "DIRECT_WEB" && booking.channel.otaName === "Website";

/**
 * Call this from your webhook route once the signature is checked, then answer 2xx at once. Deliveries are
 * at-least-once: remember event.id too if your calendar cannot take the same booking twice.
 */
export async function onWebhookEvent(event: WebhookEvent, calendar: MyCalendar): Promise<"applied" | "ignored"> {
  switch (event.type) {
    case "direct.booking.created": // a guest booked: the room is off the count the channels hold already
    case "direct.booking.cancelled": // the guest or the hotel cancelled: the booking says CANCELLED, with cancellation.reason
      if (event.data.booking && isWebsiteBooking(event.data.booking)) {
        await calendar.setWebsiteBooking(event.data.booking);
        return "applied";
      }
      return "ignored";
    default:
      // channel.booking.* is an OTA booking: your existing code handles it. There is no direct.booking.modified.
      return "ignored";
  }
}

interface WebsiteBookingsPage {
  since: string;
  items: WebsiteBooking[];
  more: boolean;
  nextCursor: string | null;
}

/**
 * Apply every website booking changed since the last one you applied. since is on a booking's last change, so
 * a cancellation lists the booking again; the oldest change comes first. On the first run pass `firstSince`,
 * the date of the oldest booking your PMS needs to know of: with none, the API reads the last seven days.
 */
export async function catchUpWebsiteBookings(calendar: MyCalendar, propertyId?: number, firstSince?: string): Promise<number> {
  const since = (await calendar.lastSeen()) ?? firstSince;
  let cursor: string | undefined;
  let applied = 0;
  let newest: string | undefined;
  for (;;) {
    // While `more` is true, ask again with cursor = nextCursor. A cursor replaces since.
    const page = await zs<WebsiteBookingsPage>("/direct-bookings", { propertyId, query: { since: cursor ? undefined : since, limit: 100, cursor } });
    for (const booking of page.items) {
      await calendar.setWebsiteBooking(booking);
      newest = booking.updatedAt;
      applied++;
    }
    if (!page.more || !page.nextCursor) break;
    cursor = page.nextCursor;
  }
  // Start the next read at the last change you saw: it lists that booking once more, which is harmless.
  if (newest) await calendar.saveLastSeen(newest);
  return applied;
}

export interface AvailabilityUpdate {
  roomTypeId: number;
  dateFrom: string;
  dateTo: string;
  /** The rooms left to sell: absolute, not a change. */
  available: number;
}

/**
 * Your PMS's full push of room counts. The website bookings come first, so the counts you work out already
 * hold the rooms they took; the push then never reopens a room a guest has booked.
 */
export async function pushRoomCounts(calendar: MyCalendar, countsFromMyCalendar: () => Promise<AvailabilityUpdate[]>, propertyId?: number) {
  await catchUpWebsiteBookings(calendar, propertyId);
  const updates = await countsFromMyCalendar(); // read AFTER the catch-up, never before it
  return zs("/availability", { method: "PUT", body: { updates }, propertyId });
}

Reading them: GET /direct-bookings

The answer has since, items, more and nextCursor, as GET /channel-bookings has, and each item is the booking object the webhook carries. Page while more is true, passing nextCursor as cursor. On the first read pass as since the date of the oldest booking your PMS needs to know of; after that, the time of the last change you applied. GET /direct-bookings/{bookingId} reads one: 404 BOOKING_NOT_FOUND for a booking that is not this property's or was not made on its website.

GET /direct-bookings takes the same since, status, limit and cursor as GET /channel-bookings and pages the same way. Scope direct-bookings:read, granted separately from channel-bookings:read. A booking deleted in ZimmerStack stays listed, as CANCELLED.

Base URL https://api.zimmerstack.com/api/v1/connect-api/v1
GET/direct-bookingsdirect-bookings:read

The bookings guests made on the hotel's own website, in the webhook's shape

Scope direct-bookings:read. The bookings of the ZimmerStack booking engine on this property: the pull beside the direct.booking.* webhooks (x-zimmerstack.directBookings). Oldest change first; since (default the last 7 days) is on the booking's last change so a cancellation is listed again; while more is true, ask again with cursor = nextCursor. A booking deleted in ZimmerStack stays listed, as CANCELLED. Read it before a full availability push.

since (query)
Changed on or after this instant (ISO 8601); default: the last 7 days
status (query)
Only confirmed or only cancelled; default both
limit (query)
Default 50
cursor (query)
The previous page's nextCursor; takes precedence over since. One this API did not issue is 400 VALIDATION
Answer (data)
{
  "since": "2026-10-23T12:00:00.000Z",
  "items": [
    {
      "id": 100001,
      "reference": "TEST-WEB-4H7P9D",
      "status": "CONFIRMED",
      "stayStatus": "UPCOMING",
      "channel": {
        "otaName": "Website",
        "otaReservationCode": "TEST-WEB-4H7P9D",
        "source": "DIRECT_WEB",
        "sourceGroup": "DIRECT"
      },
      "stay": {
        "checkIn": "2026-11-13",
        "checkOut": "2026-11-15",
        "nights": 2,
        "dayUse": false
      },
      "guest": {
        "fullName": "Asha Verma",
        "firstName": "Asha",
        "lastName": "Verma",
        "phone": "+919876500000",
        "email": "asha.verma@example.com",
        "country": "IN",
        "language": "en"
      },
      "guestNotes": null,
      "occupancy": {
        "adults": 2,
        "children": 0
      },
      "rooms": [
        {
          "roomTypeId": 412,
          "ratePlanId": 901,
          "roomTypeName": "Deluxe Sea View",
          "mealPlan": "CP",
          "adults": 2,
          "children": 0,
          "checkIn": "2026-11-13",
          "checkOut": "2026-11-15",
          "nights": 2,
          "dayUse": false,
          "ratePerNight": 2700,
          "amount": 5400,
          "status": "UPCOMING"
        }
      ],
      "amounts": {
        "currency": "INR",
        "total": 5400,
        "paid": 1080,
        "balanceDue": 4320,
        "paymentCollect": "property"
      },
      "finance": null,
      "cancellation": null,
      "createdAt": "2026-10-30T12:00:00.000Z",
      "updatedAt": "2026-10-30T12:00:00.000Z"
    }
  ],
  "more": false,
  "nextCursor": null
}
Answer fields (54)
  • sincerequiredstring

    The instant the list starts at, echoed

  • itemsrequiredarray of objects

    Oldest change first — exactly the booking object the webhooks carry

  • items[].idrequiredinteger
  • items[].referencerequiredstring
  • items[].statusrequired"CONFIRMED" · "CANCELLED"
  • items[].stayStatusrequiredstring
  • items[].channelrequiredobject
  • items[].channel.otaNamerequiredstring
  • items[].channel.otaReservationCoderequiredstring
  • items[].channel.sourcerequiredstring
  • items[].channel.sourceGrouprequiredstring
  • items[].stayrequiredobject
  • items[].stay.checkInrequiredstring
  • items[].stay.checkOutrequiredstring
  • items[].stay.nightsrequiredinteger
  • items[].stay.dayUserequiredboolean
  • items[].guestrequiredobject
  • items[].guest.fullNamerequiredstring
  • items[].guest.firstNamerequiredstring or null
  • items[].guest.lastNamerequiredstring or null
  • items[].guest.phonestring or null
  • items[].guest.emailstring or null
  • items[].guest.countryrequiredstring or null
  • items[].guest.languagerequiredstring or null
  • items[].guestNotesrequiredstring or null
  • items[].occupancyrequiredobject
  • items[].occupancy.adultsrequiredinteger
  • items[].occupancy.childrenrequiredinteger
  • items[].roomsrequiredarray of objects
  • items[].rooms[].roomTypeIdrequiredinteger
  • items[].rooms[].roomTypeNamerequiredstring
  • items[].rooms[].ratePlanIdinteger or null
  • items[].rooms[].mealPlanrequired"EP" · "CP" · "MAP" · "AP"
  • items[].rooms[].adultsrequiredinteger
  • items[].rooms[].childrenrequiredinteger
  • items[].rooms[].checkInrequiredstring
  • items[].rooms[].checkOutrequiredstring
  • items[].rooms[].nightsrequiredinteger
  • items[].rooms[].dayUserequiredboolean
  • items[].rooms[].ratePerNightrequirednumber
  • items[].rooms[].amountrequirednumber
  • items[].rooms[].statusrequiredstring
  • items[].amountsrequiredobject
  • items[].amounts.currencyrequiredstring
  • items[].amounts.totalrequirednumber
  • items[].amounts.paidrequirednumber
  • items[].amounts.balanceDuerequirednumber
  • items[].amounts.paymentCollectrequired"ota" · "property" · "unknown"
  • items[].financerequiredobject or any or null
  • items[].cancellationrequiredobject or any or null
  • items[].createdAtrequiredstring
  • items[].updatedAtrequiredstring
  • morerequiredboolean

    More rows matched than limit: ask again with cursor = nextCursor

  • nextCursorrequiredstring or null

    Pass as cursor for the next page; null when there is no more

  • 200OK
  • 401Missing, malformed, unknown or revoked key (data.code API_KEY_INVALID | API_KEY_REVOKED)
  • 403The key lacks the scope this route needs (SCOPE_MISSING, details.needed / details.held), or the request came from outside the key's address allowlist (IP_NOT_ALLOWED)
  • 404X-ZS-Property names a property this key may not act on (PROPERTY_NOT_FOUND): for a company key, one outside its hotels; for a hotel key, any other property. A company key without the header is 400 PROPERTY_REQUIRED
  • 409The property is deleted or demo (PROPERTY_UNAVAILABLE); on an ARI route its channel manager is off (CHANNEL_MANAGER_DISABLED), or, on a company key, its rates are not the source of truth (ARI_NOT_AUTHORITATIVE); on a booking route it has no PMS (PMS_NOT_AVAILABLE)
  • 429A budget was exhausted — data.scope names it (ip · ip-auth · requests · writes · property · property-writes · cells · company · global, or one of the long budgets of x-zimmerstack.shield); honour Retry-After and pace on the RateLimit header (x-zimmerstack.rateLimits)
GET/direct-bookings/{bookingId}direct-bookings:read

One website booking, the webhook's shape

Scope direct-bookings:read. 404 for a booking that is not this property's or was not made on its website.

bookingId (path, required)
Answer (data)
{
  "id": 100001,
  "reference": "TEST-WEB-4H7P9D",
  "status": "CONFIRMED",
  "stayStatus": "UPCOMING",
  "channel": {
    "otaName": "Website",
    "otaReservationCode": "TEST-WEB-4H7P9D",
    "source": "DIRECT_WEB",
    "sourceGroup": "DIRECT"
  },
  "stay": {
    "checkIn": "2026-11-13",
    "checkOut": "2026-11-15",
    "nights": 2,
    "dayUse": false
  },
  "guest": {
    "fullName": "Asha Verma",
    "firstName": "Asha",
    "lastName": "Verma",
    "phone": "+919876500000",
    "email": "asha.verma@example.com",
    "country": "IN",
    "language": "en"
  },
  "guestNotes": null,
  "occupancy": {
    "adults": 2,
    "children": 0
  },
  "rooms": [
    {
      "roomTypeId": 412,
      "ratePlanId": 901,
      "roomTypeName": "Deluxe Sea View",
      "mealPlan": "CP",
      "adults": 2,
      "children": 0,
      "checkIn": "2026-11-13",
      "checkOut": "2026-11-15",
      "nights": 2,
      "dayUse": false,
      "ratePerNight": 2700,
      "amount": 5400,
      "status": "UPCOMING"
    }
  ],
  "amounts": {
    "currency": "INR",
    "total": 5400,
    "paid": 1080,
    "balanceDue": 4320,
    "paymentCollect": "property"
  },
  "finance": null,
  "cancellation": null,
  "createdAt": "2026-10-30T12:00:00.000Z",
  "updatedAt": "2026-10-30T12:00:00.000Z"
}
Answer fields (50)
  • idrequiredinteger
  • referencerequiredstring
  • statusrequired"CONFIRMED" · "CANCELLED"
  • stayStatusrequiredstring
  • channelrequiredobject
  • channel.otaNamerequiredstring
  • channel.otaReservationCoderequiredstring
  • channel.sourcerequiredstring
  • channel.sourceGrouprequiredstring
  • stayrequiredobject
  • stay.checkInrequiredstring
  • stay.checkOutrequiredstring
  • stay.nightsrequiredinteger
  • stay.dayUserequiredboolean
  • guestrequiredobject
  • guest.fullNamerequiredstring
  • guest.firstNamerequiredstring or null
  • guest.lastNamerequiredstring or null
  • guest.phonestring or null
  • guest.emailstring or null
  • guest.countryrequiredstring or null
  • guest.languagerequiredstring or null
  • guestNotesrequiredstring or null
  • occupancyrequiredobject
  • occupancy.adultsrequiredinteger
  • occupancy.childrenrequiredinteger
  • roomsrequiredarray of objects
  • rooms[].roomTypeIdrequiredinteger
  • rooms[].roomTypeNamerequiredstring
  • rooms[].ratePlanIdinteger or null
  • rooms[].mealPlanrequired"EP" · "CP" · "MAP" · "AP"
  • rooms[].adultsrequiredinteger
  • rooms[].childrenrequiredinteger
  • rooms[].checkInrequiredstring
  • rooms[].checkOutrequiredstring
  • rooms[].nightsrequiredinteger
  • rooms[].dayUserequiredboolean
  • rooms[].ratePerNightrequirednumber
  • rooms[].amountrequirednumber
  • rooms[].statusrequiredstring
  • amountsrequiredobject
  • amounts.currencyrequiredstring
  • amounts.totalrequirednumber
  • amounts.paidrequirednumber
  • amounts.balanceDuerequirednumber
  • amounts.paymentCollectrequired"ota" · "property" · "unknown"
  • financerequiredobject or any or null
  • cancellationrequiredobject or any or null
  • createdAtrequiredstring
  • updatedAtrequiredstring
  • 200OK
  • 401Missing, malformed, unknown or revoked key (data.code API_KEY_INVALID | API_KEY_REVOKED)
  • 403The key lacks the scope this route needs (SCOPE_MISSING, details.needed / details.held), or the request came from outside the key's address allowlist (IP_NOT_ALLOWED)
  • 404No website booking with this id on this property; on a company key, PROPERTY_NOT_FOUND when X-ZS-Property names a property it may not act on
  • 409The property is deleted or demo (PROPERTY_UNAVAILABLE); on an ARI route its channel manager is off (CHANNEL_MANAGER_DISABLED), or, on a company key, its rates are not the source of truth (ARI_NOT_AUTHORITATIVE); on a booking route it has no PMS (PMS_NOT_AVAILABLE)
  • 429A budget was exhausted — data.scope names it (ip · ip-auth · requests · writes · property · property-writes · cells · company · global, or one of the long budgets of x-zimmerstack.shield); honour Retry-After and pace on the RateLimit header (x-zimmerstack.rateLimits)

OTA bookings (GET /channel-bookings), front-desk bookings and bookings a key created (GET /bookings) are never listed here.

the pull, before a full push
curl "https://api.zimmerstack.com/api/v1/connect-api/v1/direct-bookings?since=2026-11-01T00:00:00.000Z&limit=100" \
  -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY"
# while "more" is true, ask again with &cursor=<nextCursor> (the cursor replaces since)
# A company key also sends: -H "X-ZS-Property: <the hotel's id>"

Cancellations

Who can cancel
The guest, on the booking page, or the hotel, by cancelling or deleting the booking in ZimmerStack. cancellation.reason is "Cancelled by the guest" or "Cancelled by the hotel".
What your PMS does
Give the nights back in your own calendar, and keep the booking as cancelled. The room is on sale again on the channels; your next push should say so.
A deleted booking
A booking the hotel deleted in ZimmerStack stays listed by GET /direct-bookings, as CANCELLED, with every room.
Not by your PMS
Your PMS cannot cancel a website booking through the API yet. A guest who asks you to cancel is sent to the booking page, or the hotel cancels it in ZimmerStack.

Trying it in the sandbox

POST /sandbox/bookings with otaName "Website" simulates one and sends the real direct.booking.created; its cancel sends direct.booking.cancelled. Its modify is 409 BOOKING_NOT_MODIFIABLE.

  1. 1

    Register a sandbox endpoint

    On a sandbox, with a test key that holds the channel-manager scopes (the Sandbox page explains how to get one), register a webhook endpoint and tick the two direct types.
  2. 2

    Simulate a website booking

    POST /sandbox/bookings with "otaName": "Website"; the other fields are as for an OTA booking. The sandbox's availability goes down by the rooms booked, and your endpoint receives the real direct.booking.created, signed, with mode "test". paidByOta: true means the guest paid online, in full.
  3. 3

    Read it back, then cancel it

    GET /direct-bookings lists it. POST /sandbox/bookings/{bookingId}/cancel gives the rooms back and your endpoint receives direct.booking.cancelled.
  4. 4

    Know what it refuses

    POST /sandbox/bookings/{bookingId}/modify on a website booking is 409 BOOKING_NOT_MODIFIABLE: there is no modified event, because the real booking engine never changes a booking's dates.
a simulated website booking
curl -X POST https://api.zimmerstack.com/api/v1/connect-api/v1/sandbox/bookings \
  -H "Authorization: Bearer zsk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"roomTypeId":412,"checkIn":"2026-12-05","nights":2,"rooms":1,"adults":2,"guestName":"Asha Verma","otaName":"Website","paidByOta":true}'
# Your endpoint receives direct.booking.created. Read it back: GET https://api.zimmerstack.com/api/v1/connect-api/v1/direct-bookings
# Cancel it: POST https://api.zimmerstack.com/api/v1/connect-api/v1/sandbox/bookings/<bookingId>/cancel   (your endpoint receives direct.booking.cancelled)

More on keys and the simulated routes: Sandbox. Need a key? Sign up as a partner (free), or ask the hotel's owner for a sandbox key.

With the Node package

From @zimmerstack/connect 0.3.0: isWebsiteBookingEvent(event) and isOtaBookingEvent(event) narrow a verified event, and zs.directBookings.list(), .get(id) and .all({ since }) read the pull and follow the cursor for you. zs.sandbox.bookings.create({ …, otaName: "Website" }) simulates one. The package page has the example route that handles both families.

What is not there yet

No modified event
The booking engine never changes a booking's dates, so there is no direct.booking.modified.
No cancel by API
Your PMS cannot cancel a website booking through the API yet; cancellations come from the guest's booking page or from the hotel in ZimmerStack.
No guard on the count
ZimmerStack does not stop a push that puts the sold room back on sale. Applying the booking first is your PMS's job.
Not the other direction
Bookings your own booking engine hands to the ZimmerStack PMS are a different thing: POST /bookings, on the Bookings page.

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:11:24 UTC.