Skip to content

Guides

Prices per channel

One price per rate plan per night goes to every channel. To sell higher on Booking.com than on MakeMyTrip, give a channel a modifier: a few steps the channel manager applies to every price it sends that channel. Read it, set it, and send the prices again, all by API.

The model

One price per rate plan per night goes to every channel the plan is mapped to. A channel's modifier is the one thing that differs per channel: up to five ordered steps (raise or lower, by a percentage or a fixed amount in major units) the channel manager applies to every price it sends that channel. GET /channels shows each channel's steps; PUT /channels/{channelId}/modifier replaces them (scope channel-modifiers:write, granted separately: one call moves every price on that channel).

Your grid
GET /rates always answers the price before any modifier. What a channel is sent is that price with the channel's steps applied in order.
A step
Raise or lower, by a percentage of the price or by a fixed amount in major units of the property's currency. Up to five, applied in the order you send them.
The whole list
A write replaces what the channel holds. An empty list removes the modifier: prices go to that channel as they are.
The owner's own markup
markupPlan on GET /channels is a separate adjustment the owner may have set in the ZimmerStack Channels app; it applies before the modifier and is read-only here.

When a modifier takes effect

POST /rates/resend (scope ari:write) sends the property's prices and stay rules to the channels again, unchanged, so every night picks the current modifiers up. Re-sending the same price through PUT /rates does nothing: a value our record already holds is dropped before anything is sent. The re-send is the way, and a hotel may ask for it only a few times a day (data.scope rate-resends-day).

The workflow: three calls

  1. 1

    GET /channels

    find the channel (channelId, kind) and read the steps it holds
  2. 2

    PUT /channels/{channelId}/modifier with the whole list of steps; [] removes the modifier

  3. 3

    POST /rates/resend if nights already on the channel should move too, then watch rates.dirtyCells on GET /sync fall to 0

the three calls
# 1. Which channels, and what each one holds
curl "https://api.zimmerstack.com/api/v1/connect-api/v1/channels" -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY"

# 2. Booking.com is sent 18 % more, then 200 less (the whole list of steps, in order)
curl -X PUT "https://api.zimmerstack.com/api/v1/connect-api/v1/channels/$CHANNEL_ID/modifier" \
  -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: $(uuidgen)" \
  -d '{ "steps": [ { "action": "increase", "type": "percent", "value": 18 },
                   { "action": "decrease", "type": "fixed",   "value": 200 } ] }'

# 3. Nights already on the channel keep their price until sent again. Send them again:
curl -X POST "https://api.zimmerstack.com/api/v1/connect-api/v1/rates/resend" \
  -H "Authorization: Bearer $ZIMMERSTACK_CONNECT_KEY" \
  -H "x-idempotency-key: $(uuidgen)"

Setting a modifier needs the scope channel-modifiers:write, which a key holds only when the hotel's owner ticked it (Admin → Developers → API keys) or, for a software vendor, when the key was created with it in the partner portal. One call with it moves every price sent to that channel, so it is granted apart from ari:write. Reading and the re-send need only the ARI pair.

Read: each channel and what it holds

GET /channels (data)
{
  "asOf": "2026-10-30T20:15:04.000Z",
  "channels": [
    {
      "channelId": "7c1d8a3e-5f2b-4d6a-9e0c-1b2a3c4d5e6f",
      "kind": "BookingCom",
      "title": "Booking.com — The Lantern House",
      "seenAt": "2026-10-30T20:15:04.000Z",
      "openIssues": [],
      "modifier": [
        {
          "action": "increase",
          "type": "percent",
          "value": 18
        }
      ],
      "markupPlan": null
    },
    {
      "channelId": "0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d",
      "kind": "Expedia",
      "title": "Expedia — The Lantern House",
      "seenAt": "2026-10-30T20:15:04.000Z",
      "openIssues": [
        {
          "event": "rate_error",
          "raisedAt": "2026-10-30T09:40:11.000Z"
        }
      ],
      "modifier": [],
      "markupPlan": null
    }
  ],
  "propertyIssues": []
}
  • modifier is the list of steps. [] means prices go to that channel as they are.
  • null means the channel holds a rule set by hand in the channel manager that this API cannot express. Setting a modifier replaces it.
  • A modifier you set through this API shows here at once. One the hotel changed on its own screens, and the list of channels itself, are refreshed nightly (asOf): a channel connected today appears tomorrow.

Set: one channel's steps

PUT /channels/{channelId}/modifier
{
  "steps": [
    {
      "action": "increase",
      "type": "percent",
      "value": 18
    },
    {
      "action": "decrease",
      "type": "fixed",
      "value": 200
    }
  ]
}

The answer is a plain 200, not a 202: the modifier is applied to the channel while the request runs and read back, so 200 means the channel holds it. changed: false means it already held exactly these steps; nothing was sent and nothing was counted, so sending the same modifier twice is safe.

Send the prices again

POST /rates/resend → 202 (data)
{
  "from": "2026-11-12",
  "to": "2027-11-12",
  "cells": 1098,
  "parkedLeft": 0,
  "watch": "/api/v1/connect-api/v1/sync",
  "notice": "The prices and stay rules of these nights are on their way to the channels again, unchanged, at the usual pace. A full calendar takes minutes."
}

Every rate-plan night of the writable horizon is marked to go out again, unchanged, and travels like any write: paced, never lost. A full calendar takes minutes. Watch rates.dirtyCells on GET /sync fall to 0. A hotel may ask 3 times a day, so make it a deliberate button (“Apply to nights already on sale”) and never call it automatically.

Limits and refusals

  • RuleThe band
    DetailThe steps together may not lower a price by more or raise it by more than the band: 422 MODIFIER_OUT_OF_BAND, nothing changed. A fixed amount is judged at the property's lowest and highest standing price. Today: at most 50% lower and 100% higher.
    Answer422 MODIFIER_OUT_OF_BAND
  • RuleChanges a day
    Detail6 modifier changes per hotel per rolling day, all its channels and keys together. Steps a channel already holds are not counted.
    Answer429 · modifier-changes-day
  • RuleRe-sends a day
    Detail3 per hotel per rolling day.
    Answer429 · rate-resends-day
  • RuleA shared connection
    DetailA connection that serves more than one property (one Airbnb or Booking.com account for sister hotels) is refused, 409 CHANNEL_SHARED: its modifier would move another hotel's prices. The hotels' owner sets it in ZimmerStack.
    Answer409 CHANNEL_SHARED
  • RuleThe channel
    DetailMust be one GET /channels lists for this property.
    Answer404 CHANNEL_NOT_FOUND
  • RuleThe channel manager
    DetailIf it does not take the modifier, nothing is changed here either.
    Answer502 CHANNEL_MANAGER_ERROR

A 429 carries Retry-After; a paused or suspended integration is refused here as on PUT /rates. Every code is on Errors.

In your grid

Keep the grid on the price before any modifier, and show what a channel is sent beside it: the price with that channel's steps applied in order. channelPrice(4500, steps) for the sample above is 5,110: 4,500 raised by 18 % is 5,310, then 200 less.

modifiers.ts · read, compute, set, send again
/**
 * Prices that differ per channel. One price per rate plan per night goes to every channel; a channel's
 * modifier is what differs: ordered steps the channel manager applies to every price it sends that channel.
 * Runs on your server, on top of zimmerstack.ts. The key needs the scope channel-modifiers:write to set one.
 */
import { zs } from "./zimmerstack";

export interface ModifierStep {
  action: "increase" | "decrease";
  type: "percent" | "fixed";
  /** 18 with "percent" is 18 %; 200 with "fixed" is 200.00 in the property's currency. Always positive. */
  value: number;
}

export interface Channel {
  channelId: string;
  /** BookingCom, GoMMT, Agoda, Airbnb, Expedia, … */
  kind: string;
  title: string | null;
  /** [] = prices go as they are. null = a rule set by hand that this API cannot express; setting one replaces it. */
  modifier: ModifierStep[] | null;
}

/** The connected channels, each with the steps it holds. Answered from ZimmerStack's record: read it when the screen opens. */
export async function listChannels(propertyId?: number): Promise<Channel[]> {
  const out = await zs<{ channels: Channel[] }>("/channels", { propertyId });
  return out.channels;
}

/**
 * What a channel is sent for a price, in MAJOR units: the steps applied in order. Your grid holds the price
 * before any modifier (that is what GET /rates returns); use this to show "on Booking.com" beside it.
 */
export function channelPrice(rate: number, steps: ModifierStep[]): number {
  let minor = Math.round(rate * 100);
  for (const step of steps) {
    const sign = step.action === "decrease" ? -1 : 1;
    minor = step.type === "percent" ? minor * (1 + (sign * step.value) / 100) : minor + sign * Math.round(step.value * 100);
  }
  return Math.round(minor) / 100;
}

export interface ModifierResult {
  channelId: string;
  modifier: ModifierStep[];
  /** false when the channel already held exactly these steps: nothing was sent and nothing was counted. */
  changed: boolean;
  notice: string;
}

/**
 * Replace a channel's steps with the list given ([] removes them). 200 means the channel holds them.
 *
 * ONE CALL MOVES EVERY PRICE SENT TO THAT CHANNEL FROM THEN ON. Call it when a person saved the setting,
 * never from a loop, a timer or a test against a live key. Prices already on the channel stay as they are
 * until those nights are sent again: see resendRates.
 */
export async function setModifier(channelId: string, steps: ModifierStep[], propertyId?: number): Promise<ModifierResult> {
  return zs<ModifierResult>("/channels/" + encodeURIComponent(channelId) + "/modifier", { method: "PUT", body: { steps }, propertyId });
}

export interface ResendAccepted {
  from: string;
  to: string;
  /** Rate-plan nights marked to be sent again. Watch rates.dirtyCells on GET /sync fall to 0. */
  cells: number;
  watch: string;
}

/**
 * Send the property's prices to the channels again, unchanged, so nights already there pick the current
 * modifiers up. A hotel may ask a few times a day: offer it as a button after a modifier change, and never
 * call it automatically. Re-sending the same price through PUT /rates does nothing: an unchanged value is
 * dropped before anything is sent.
 */
export async function resendRates(propertyId?: number): Promise<ResendAccepted> {
  return zs<ResendAccepted>("/rates/resend", { method: "POST", propertyId });
}

It sits on the client from Build a rate grid (zimmerstack.ts), and like those files it is checked against the contract whenever this site changes.

The other way: a rate plan per OTA

A modifier is one rule for every night on a channel. When one OTA needs prices of its own on particular nights (a weekend rate on Booking.com only), give it a rate plan of its own instead: create a second plan with PUT /catalog/rate-plans (scope catalog:write), for example “Deluxe, breakfast (Booking.com)”. The hotel maps that OTA's rates to it once, in the ZimmerStack Channels app. From then on it is one more row in your grid, priced with PUT /rates like any plan. A hotel holds a bounded number of plans (structure limits).

Try it on the sandbox

A sandbox has three pretend channels (Booking.com, MakeMyTrip, Agoda) so the whole workflow can be tried with a test key; nothing leaves our record. The same three calls, the same refusals, the same budgets; POST /rates/resend lands in the record within a minute. The sandbox has the rest.

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.