Promotional campaigns

Hotels run public promotions, including time-limited flash sales, and distribute private codes through email, social, or partner channels. The Booking Engine API exposes both: read the active promotion to display it, and seed a code into the session to unlock the rates it grants.

The examples reuse the OAuth 1.0 signing from the Quick start. Replace {sessionId} with your session.

Show the active promotion

GET /v2/{sessionId}/promotion returns the latest active public promotion for the session’s hotel, or 204 No Content when none is running. Use it to render a promotional banner, with a countdown when the promotion is a flash sale.

curl --request GET \
  --url 'https://{apiBaseUrl}/v2/{sessionId}/promotion' \
  --header 'Authorization: OAuth ...'

const url = "https://{apiBaseUrl}/v2/{sessionId}/promotion";

const response = await fetch(url, {
  method: "GET",
  headers: { ...oauth.toHeader(oauth.authorize({ url, method: "GET" }, token)) },
});

const promotion = response.status === 204 ? null : await response.json();

response = session.get("https://{apiBaseUrl}/v2/{sessionId}/promotion")
promotion = response.json() if response.status_code == 200 else None

$response = $client->get('v2/{sessionId}/promotion');
$promotion = $response->getStatusCode() === 204
    ? null
    : json_decode($response->getBody(), true);

var request = new RestRequest("/v2/{sessionId}/promotion", Method.Get);

var response = await client.ExecuteAsync(request);
var promotion = response.StatusCode == HttpStatusCode.NoContent
    ? (JsonElement?)null
    : JsonDocument.Parse(response.Content!).RootElement;

HttpGet request = new HttpGet("https://{apiBaseUrl}/v2/{sessionId}/promotion");
consumer.sign(request);

JsonNode promotion = null;
try (CloseableHttpResponse response = client.execute(request)) {
    if (response.getStatusLine().getStatusCode() == 200) {
        promotion = mapper.readTree(EntityUtils.toString(response.getEntity()));
    }
}

A running promotion comes back with its discount and, for a flash sale, a deadline:

{
  "id": "0b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "description": "Spring flash sale",
  "isPublic": true,
  "isFlashSales": true,
  "displayCountdown": true,
  "endDate": "2026-12-10T00:00:00Z",
  "discount": { "calculationMode": "Percentage", "percent": 15 }
}

Show the countdown only when displayCountdown is true, and hide the banner on a 204. A promo code converts best when its landing page opens straight onto the offer it unlocks. Seed the code into context.promoCode when you create the session (see the Quick start), then search as usual: the results are scoped to the rates the code grants. Confirm the code resolved by reading the session scope:

curl --request GET \
  --url 'https://{apiBaseUrl}/v2/{sessionId}/session/scope' \
  --header 'Authorization: OAuth ...'

const url = "https://{apiBaseUrl}/v2/{sessionId}/session/scope";

const response = await fetch(url, {
  method: "GET",
  headers: { ...oauth.toHeader(oauth.authorize({ url, method: "GET" }, token)) },
});

const scope = await response.json();
const promoCode = scope.activePromoCode;

response = session.get("https://{apiBaseUrl}/v2/{sessionId}/session/scope")

scope = response.json()
promo_code = scope.get("activePromoCode")

$response = $client->get('v2/{sessionId}/session/scope');

$scope = json_decode($response->getBody(), true);
$promoCode = $scope['activePromoCode'] ?? null;

var request = new RestRequest("/v2/{sessionId}/session/scope", Method.Get);

var response = await client.ExecuteAsync(request);
var scope = JsonDocument.Parse(response.Content!).RootElement;
var promoCode = scope.GetProperty("activePromoCode");

HttpGet request = new HttpGet("https://{apiBaseUrl}/v2/{sessionId}/session/scope");
consumer.sign(request);

JsonNode scope;
try (CloseableHttpResponse response = client.execute(request)) {
    scope = mapper.readTree(EntityUtils.toString(response.getEntity()));
}
JsonNode promoCode = scope.path("activePromoCode");

{
  "activePromoCode": {
    "type": "RateCode",
    "code": "AUTUMN2026",
    "rateIds": [32643]
  }
}

type tells you what the code is (RateCode, OfferCode, or DiscountCode), and rateIds lists the rates it unlocked. When the code does not apply, session creation can return 400 with Code: InvalidPromoCode (unknown code), InvalidPromoCodeBookingPeriod (booked outside the campaign window), or InvalidPromoCodeStayPeriod (stay dates outside the offer). Catch these codes and show a fallback explaining why the code is not valid for this stay, rather than a raw error.

Tips

Pass the code through the URL. A campaign link like https://book.example.com/offer?code=AUTUMN2026 opens the page on the offer in one flow, with no form.
Treat a 204 as “no promotion”, not an error. Hide the banner when no promotion is active.
Log every code, even unresolved ones. Marketing needs both how many guests arrived with a code and how many got a valid offer: the gap surfaces a misconfigured offer fast.

Get a promotion

Full schema for the promotion endpoint.

Create a session

Seed context.promoCode when you open the session.

Get started

Build

Resources

Promotional campaigns

Show the active promotion

Tips

Get a promotion

Create a session

​Show the active promotion

​Build a promo-code landing page

​Tips

​Related

Get a promotion

Create a session

Show the active promotion

Build a promo-code landing page

Tips

Related