Promo code landing

A promo code distributed through email, social, or a partner channel converts best when its landing page surfaces the offer behind it directly. One Stay quotation call with referenceRateCode set returns only the rate the code unlocks, ready to render.

Prerequisites

Before building the landing page, make sure you have:

A working Quotation call. If not, follow the Quick start first.
A hotel ID and a group ID for the property the campaign points at.
An arrival date and a night count, supplied by the campaign URL or a small form on the page.
A rate code or private offer code (for example AUTUMN2026), shared by the revenue manager who set the offer up.

How it works

The Stay quotation endpoint accepts a referenceRateCode filter on the ratePlans entry. With it set, the API restricts the quote to the matching rate plan or private offer code: a public rate code like BAR returns the public offer, a private code like AUTUMN2026 returns the campaign-only or negotiated offer. Without it, the endpoint returns the whole catalogue, which is the Bookable offers showcase pattern. Two outcomes worth handling on the page:

Code applies: the response carries one rate plan with one or more entities. Render the offer.
Code does not apply (expired, restricted to other dates, wrong hotel, wrong party): the response is a 200 OK with empty ratePlans or no Available entity. Show a fallback explaining the code is not valid for the chosen stay, rather than a generic error.

A single call covers the whole landing page. Cancellation conditions and included articles arrive in the same response, and adding TaxesAndFees to the layout brings the tax breakdown with them, so the page stays one round trip away from the conversion CTA.

Build the landing page

The examples below assume the OAuth signing setup from the Quick start.

Quote the stay with the code applied

Call the Stay quotation endpoint once with the chosen stay and the rate code on ratePlans[].referenceRateCode. Keep layout.levels[*].properties to the columns the landing page actually displays.

curl --request POST \
  --url https://{apiBaseUrl}/Planning/2018A/Quotation/GetStayPlanning \
  --header 'Authorization: OAuth ...' \
  --header 'Content-Type: application/json' \
  --data '{
    "arrivalDate": "2026-12-07",
    "nightCount": 3,
    "guests": [{"adults": 2}],
    "filter": {
      "ratePlans": [{
        "groupId": <groupId>,
        "referenceRateCode": "AUTUMN2026",
        "hotels": {"exceptions": [<hotelId>], "default": "Excluded"}
      }],
      "currencies": {"exceptions": ["EUR"], "default": "Excluded"}
    },
    "layout": {
      "levels": [{
        "name": "ArticleRate",
        "properties": [
          "Status",
          "TotalPrice",
          "IncludedArticles",
          "CancellationCondition",
          "Occupancies"
        ]
      }]
    }
  }'

const url = "https://{apiBaseUrl}/Planning/2018A/Quotation/GetStayPlanning";

const response = await fetch(url, {
  method: "POST",
  headers: { ...authHeaders, "Content-Type": "application/json" },
  body: JSON.stringify({
    arrivalDate: "2026-12-07",
    nightCount: 3,
    guests: [{ adults: 2 }],
    filter: {
      ratePlans: [
        {
          groupId: <groupId>,
          referenceRateCode: "AUTUMN2026",
          hotels: { exceptions: [<hotelId>], default: "Excluded" },
        },
      ],
      currencies: { exceptions: ["EUR"], default: "Excluded" },
    },
    layout: {
      levels: [
        {
          name: "ArticleRate",
          properties: [
            "Status",
            "TotalPrice",
            "IncludedArticles",
            "CancellationCondition",
            "Occupancies",
          ],
        },
      ],
    },
  }),
});
const data = await response.json();

response = session.post(
    "https://{apiBaseUrl}/Planning/2018A/Quotation/GetStayPlanning",
    json={
        "arrivalDate": "2026-12-07",
        "nightCount": 3,
        "guests": [{"adults": 2}],
        "filter": {
            "ratePlans": [
                {
                    "groupId": <groupId>,
                    "referenceRateCode": "AUTUMN2026",
                    "hotels": {"exceptions": [<hotelId>], "default": "Excluded"},
                }
            ],
            "currencies": {"exceptions": ["EUR"], "default": "Excluded"},
        },
        "layout": {
            "levels": [
                {
                    "name": "ArticleRate",
                    "properties": [
                        "Status",
                        "TotalPrice",
                        "IncludedArticles",
                        "CancellationCondition",
                        "Occupancies",
                    ],
                }
            ]
        },
    },
)
data = response.json()

$response = $client->post('Planning/2018A/Quotation/GetStayPlanning', [
    'json' => [
        'arrivalDate' => '2026-12-07',
        'nightCount'  => 3,
        'guests'      => [['adults' => 2]],
        'filter' => [
            'ratePlans' => [[
                'groupId'           => <groupId>,
                'referenceRateCode' => 'AUTUMN2026',
                'hotels'            => ['exceptions' => [<hotelId>], 'default' => 'Excluded'],
            ]],
            'currencies' => ['exceptions' => ['EUR'], 'default' => 'Excluded'],
        ],
        'layout' => [
            'levels' => [[
                'name' => 'ArticleRate',
                'properties' => [
                    'Status',
                    'TotalPrice',
                    'IncludedArticles',
                    'CancellationCondition',
                    'Occupancies',
                ],
            ]],
        ],
    ],
]);
$data = json_decode($response->getBody(), true);

var request = new RestRequest("/Quotation/GetStayPlanning", Method.Post);
request.AddJsonBody(new
{
    arrivalDate = "2026-12-07",
    nightCount = 3,
    guests = new[] { new { adults = 2 } },
    filter = new
    {
        ratePlans = new[]
        {
            new
            {
                groupId = <groupId>,
                referenceRateCode = "AUTUMN2026",
                hotels = new { exceptions = new[] { <hotelId> }, @default = "Excluded" }
            }
        },
        currencies = new { exceptions = new[] { "EUR" }, @default = "Excluded" }
    },
    layout = new
    {
        levels = new[]
        {
            new
            {
                name = "ArticleRate",
                properties = new[]
                {
                    "Status",
                    "TotalPrice",
                    "IncludedArticles",
                    "CancellationCondition",
                    "Occupancies"
                }
            }
        }
    }
});

var response = await client.ExecuteAsync(request);
var data = JsonDocument.Parse(response.Content!).RootElement;

String body = mapper.writeValueAsString(Map.of(
    "arrivalDate", "2026-12-07",
    "nightCount", 3,
    "guests", List.of(Map.of("adults", 2)),
    "filter", Map.of(
        "ratePlans", List.of(Map.of(
            "groupId", <groupId>,
            "referenceRateCode", "AUTUMN2026",
            "hotels", Map.of(
                "exceptions", List.of(<hotelId>),
                "default", "Excluded"
            )
        )),
        "currencies", Map.of(
            "exceptions", List.of("EUR"),
            "default", "Excluded"
        )
    ),
    "layout", Map.of(
        "levels", List.of(Map.of(
            "name", "ArticleRate",
            "properties", List.of(
                "Status",
                "TotalPrice",
                "IncludedArticles",
                "CancellationCondition",
                "Occupancies"
            )
        ))
    )
));

HttpPost request = new HttpPost("https://{apiBaseUrl}/Planning/2018A/Quotation/GetStayPlanning");
request.setEntity(new StringEntity(body, "UTF-8"));
request.setHeader("Content-Type", "application/json");
consumer.sign(request);

JsonNode data;
try (CloseableHttpResponse response = client.execute(request)) {
    data = mapper.readTree(EntityUtils.toString(response.getEntity()));
}

Detect a missing or invalid code

A 200 OK with no rate plan, or a rate plan with no Available entity, means the code does not apply to the chosen stay. Treat it as a UX state, not an error: explain that the code is not valid for these dates or this hotel, and offer the public catalogue as a fallback.

const ratePlan = data.ratePlans?.[0];
const offer = ratePlan?.hotels
  ?.flatMap(hotel => hotel.entities)
  ?.find(entity => entity.status === "Available");

if (!offer) {
  renderCodeNotValid({ code: "AUTUMN2026" });
  return;
}

rate_plan = (data.get("ratePlans") or [None])[0]
offer = next(
    (
        entity
        for hotel in (rate_plan or {}).get("hotels", [])
        for entity in hotel.get("entities", [])
        if entity.get("status") == "Available"
    ),
    None,
)

if offer is None:
    render_code_not_valid({"code": "AUTUMN2026"})
    return

$ratePlan = $data['ratePlans'][0] ?? null;
$offer = null;
foreach ($ratePlan['hotels'] ?? [] as $hotel) {
    foreach ($hotel['entities'] ?? [] as $entity) {
        if (($entity['status'] ?? null) === 'Available') {
            $offer = $entity;
            break 2;
        }
    }
}

if ($offer === null) {
    renderCodeNotValid(['code' => 'AUTUMN2026']);
    return;
}

var ratePlans = data.GetProperty("ratePlans");
JsonElement? offer = null;

if (ratePlans.GetArrayLength() > 0)
{
    foreach (var hotel in ratePlans[0].GetProperty("hotels").EnumerateArray())
    {
        foreach (var entity in hotel.GetProperty("entities").EnumerateArray())
        {
            if (entity.TryGetProperty("status", out var status)
                && status.GetString() == "Available")
            {
                offer = entity;
                break;
            }
        }
        if (offer.HasValue) break;
    }
}

if (!offer.HasValue)
{
    RenderCodeNotValid(new { code = "AUTUMN2026" });
    return;
}

JsonNode ratePlan = data.path("ratePlans").path(0);
JsonNode offer = null;
for (JsonNode hotel : ratePlan.path("hotels")) {
    for (JsonNode entity : hotel.path("entities")) {
        if ("Available".equals(entity.path("status").asText())) {
            offer = entity;
            break;
        }
    }
    if (offer != null) break;
}

if (offer == null) {
    renderCodeNotValid(Map.of("code", "AUTUMN2026"));
    return;
}

Render the offer card

Display the room, total price, included articles, and cancellation condition. The referenceRateCode echoed in the response confirms the code applied is the one you sent, useful for analytics or partner attribution.

renderOfferCard({
  code: ratePlan.referenceRateCode,
  roomId: offer.roomId,
  rateId: offer.rateId,
  totalPrice: offer.totalPrice,
  currency: offer.currency,
  includedArticles: offer.articles?.includedArticles ?? [],
  cancellation: offer.cancellationCondition,
});

render_offer_card({
    "code": rate_plan["referenceRateCode"],
    "roomId": offer["roomId"],
    "rateId": offer["rateId"],
    "totalPrice": offer["totalPrice"],
    "currency": offer["currency"],
    "includedArticles": offer.get("articles", {}).get("includedArticles", []),
    "cancellation": offer.get("cancellationCondition"),
})

renderOfferCard([
    'code'             => $ratePlan['referenceRateCode'],
    'roomId'           => $offer['roomId'],
    'rateId'           => $offer['rateId'],
    'totalPrice'       => $offer['totalPrice'],
    'currency'         => $offer['currency'],
    'includedArticles' => $offer['articles']['includedArticles'] ?? [],
    'cancellation'     => $offer['cancellationCondition'] ?? null,
]);

RenderOfferCard(new
{
    code = ratePlans[0].GetProperty("referenceRateCode").GetString(),
    roomId = offer.Value.GetProperty("roomId").GetInt32(),
    rateId = offer.Value.GetProperty("rateId").GetInt32(),
    totalPrice = offer.Value.GetProperty("totalPrice").GetDecimal(),
    currency = offer.Value.GetProperty("currency").GetString()
});

renderOfferCard(Map.of(
    "code", ratePlan.path("referenceRateCode").asText(),
    "roomId", offer.path("roomId").asInt(),
    "rateId", offer.path("rateId").asInt(),
    "totalPrice", offer.path("totalPrice").asDouble(),
    "currency", offer.path("currency").asText()
));

Tips

Pass the code through the URL, not a form. A campaign link like https://book.example.com/offer?code=AUTUMN2026&arrival=2026-12-07&nights=3 lets the page render the offer in one round-trip with no friction. Reserve a form for cases where the guest types a code into an existing booking funnel.
Log the code use even when no offer comes back. Marketing teams need both numbers: how many people landed on the page with a given code, and how many of those got a valid offer. The gap surfaces an expired or misconfigured offer faster than a help ticket.

Reference

Full schema for the Stay quotation endpoint.

Best practices

Caching, performance, and resilience patterns.

Get started

Build

Resources

Prerequisites

How it works

Build the landing page

Quote the stay with the code applied

Detect a missing or invalid code

Render the offer card

Tips

Reference

Best practices

​Prerequisites

​How it works

​Build the landing page

Quote the stay with the code applied

Detect a missing or invalid code

Render the offer card

​Tips

​Related

Reference

Best practices

Prerequisites

How it works

Build the landing page

Tips

Related