Overview
Retrieves all active promotions available for a specific property through your distribution channel. Use this to display applicable discounts, coupon codes, and special offers on property detail pages.Request
GET /v1/properties/{propertyId}/promotions
Headers
| Header | Type | Required | Description |
|---|---|---|---|
Api-Key | string | Yes | Your API key for authentication. |
Channel-Id | string | Yes | Your distribution channel identifier. |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
propertyId | string | Yes | Unique identifier of the property to retrieve promotions for. |
Example Request
curl -X GET "https://sandbox.elivaas.com/v1/properties/prop_456/promotions" \
-H "Api-Key: YOUR_API_KEY" \
-H "Channel-Id: YOUR_CHANNEL_ID"
Response — 200 OK
Returns an array of Promotion objects. Returns an empty array [] if no active promotions exist.
Promotion Object
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Unique identifier for the promotion. |
code | string | No | Promotion code. For COUPON type, this is the code guests enter at checkout. |
title | string | No | Display title of the promotion (e.g., “Summer Discount”). |
description | string | Yes | Detailed description of the promotion. |
startDateTime | string (datetime) | Yes | When the promotion becomes bookable. ISO 8601 format. |
endDateTime | string (datetime) | Yes | When the promotion expires. Bookings after this time cannot use the promotion. |
stayStartDate | string (date) | Yes | Earliest check-in date the promotion applies to. null means no restriction. |
stayEndDate | string (date) | Yes | Latest check-out date the promotion applies to. null means no restriction. |
maximumUsageLimit | integer | Yes | Maximum total redemptions allowed across all guests. null means unlimited. |
usageCount | integer | Yes | Number of times the promotion has been redeemed so far. |
minimumNights | integer | Yes | Minimum stay length (nights) required for the promotion to apply. |
maximumNights | integer | Yes | Maximum stay length (nights) the promotion covers. |
discountMethod | string | No | How the discount is calculated. Values: PERCENTAGE, FLAT. |
discountType | string | Yes | Classification of the discount. |
target | string | Yes | What the discount applies to (e.g., ROOM, TOTAL). |
discountAmount | integer | Yes | Flat discount amount. Populated when discountMethod is FLAT. |
discountPercentage | double | Yes | Percentage discount. Populated when discountMethod is PERCENTAGE. |
maximumDiscountAllowed | integer | Yes | Cap on the discount amount for percentage-based promotions. Prevents excessive discounts on high-value bookings. |
minimumBookingAmount | integer | Yes | Minimum booking subtotal required before the promotion can be applied. |
status | string | No | Current status. Values: ACTIVE, INACTIVE, EXPIRED. Only ACTIVE promotions are returned by this endpoint. |
type | string | No | Promotion category. See Promotion Types. |
nonRefundable | boolean | No | true if bookings using this promotion are non-refundable. |
weekendOnly | boolean | No | true if the promotion applies only to weekend stays. |
weekdayOnly | boolean | No | true if the promotion applies only to weekday stays. |
clubbed | boolean | No | true if this promotion can be combined (stacked) with other promotions. |
lastMinuteUnit | string | Yes | Time unit for last-minute promotion eligibility. Values: HOURS, DAYS. Only present for LAST_MINUTE type. |
lastMinuteValue | integer | Yes | Time value for last-minute eligibility (e.g., 3 with DAYS means booking must be within 3 days of check-in). |
earlyBookerValueInDays | integer | Yes | Minimum days in advance the booking must be made. Only present for EARLY_BOOKER type. |
freeNights | integer | Yes | Number of free nights offered (e.g., 1 for “Stay 3, Pay 2”). Only present for FREE_NIGHT type. |
termsAndConditions | string | Yes | Terms and conditions text to display to the guest. |
icon | string | Yes | Icon identifier or URL for display purposes. |
rank | integer | Yes | Display priority. Lower values indicate higher priority. Use this to sort promotions in your UI. |
blackoutDates | object | Yes | JSON object defining dates when the promotion is not applicable. |
checkinBlackoutDates | object | Yes | JSON object defining check-in dates when the promotion is not applicable. |
rule | object | Yes | JSON object defining additional business rules and conditions for the promotion. |
Promotion Types
| Type | Description | Key Fields |
|---|---|---|
COUPON | Code-based discount applied at checkout. | code, discountMethod, discountAmount or discountPercentage |
EARLY_BOOKER | Discount for bookings made well in advance. | earlyBookerValueInDays |
LAST_MINUTE | Discount for bookings close to the check-in date. | lastMinuteUnit, lastMinuteValue |
FREE_NIGHT | Offers free nights (e.g., “Stay 3, Pay 2”). | freeNights, minimumNights |
BASIC | Standard promotion without special timing conditions. | discountMethod, discountAmount or discountPercentage |
Example Response
[
{
"id": "promo_001",
"code": "SUMMER20",
"title": "Summer Discount",
"description": "Get 20% off on stays during summer season",
"startDateTime": "2025-06-01T00:00:00",
"endDateTime": "2025-08-31T23:59:59",
"stayStartDate": "2025-06-01",
"stayEndDate": "2025-08-31",
"maximumUsageLimit": 100,
"usageCount": 25,
"minimumNights": 2,
"maximumNights": 14,
"discountMethod": "PERCENTAGE",
"discountType": "DISCOUNT",
"target": "ROOM",
"discountAmount": 0,
"discountPercentage": 20.0,
"maximumDiscountAllowed": 5000,
"minimumBookingAmount": 3000,
"status": "ACTIVE",
"type": "COUPON",
"nonRefundable": false,
"weekendOnly": false,
"weekdayOnly": false,
"clubbed": false,
"lastMinuteUnit": null,
"lastMinuteValue": null,
"earlyBookerValueInDays": null,
"freeNights": 0,
"termsAndConditions": "Valid for new bookings only. Cannot be combined with other offers.",
"icon": "discount-tag",
"rank": 1,
"blackoutDates": null,
"checkinBlackoutDates": null,
"rule": null
},
{
"id": "promo_002",
"code": "EARLY15",
"title": "Early Bird Offer",
"description": "Book 30 days in advance and get 15% off",
"startDateTime": "2025-01-01T00:00:00",
"endDateTime": "2025-12-31T23:59:59",
"stayStartDate": null,
"stayEndDate": null,
"maximumUsageLimit": null,
"usageCount": 0,
"minimumNights": 1,
"maximumNights": null,
"discountMethod": "PERCENTAGE",
"discountType": "DISCOUNT",
"target": "ROOM",
"discountAmount": 0,
"discountPercentage": 15.0,
"maximumDiscountAllowed": 3000,
"minimumBookingAmount": null,
"status": "ACTIVE",
"type": "EARLY_BOOKER",
"nonRefundable": false,
"weekendOnly": false,
"weekdayOnly": false,
"clubbed": true,
"lastMinuteUnit": null,
"lastMinuteValue": null,
"earlyBookerValueInDays": 30,
"freeNights": 0,
"termsAndConditions": "Must book at least 30 days before check-in.",
"icon": "calendar-clock",
"rank": 2,
"blackoutDates": null,
"checkinBlackoutDates": null,
"rule": null
}
]
Error Handling
| Status | Meaning | Description |
|---|---|---|
200 | Success | Promotions returned. Empty array if none are active. |
401 | Unauthorized | Missing or invalid Api-Key or Channel-Id. |
404 | Not Found | Property ID does not exist. |
500 | Internal Server Error | Unexpected error. Retry with exponential backoff. |