Skip to main content

​
Overview

The Promotions Retrieve API allows you to get all active promotions available for a specific property through your distribution channel. Promotions include coupons, early booker discounts, last-minute deals, free night offers, and more.

​
Retrieving Property Promotions

GET /v1/properties/{propertyId}/promotions

​
Path Parameters

ParameterTypeRequiredDescription
propertyIdstringYesIdentifier of the property to retrieve promotions for

​
Example Request

curl -X GET "https://api.elivaas.com/api/v1/properties/prop_456/promotions" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Channel-Id: YOUR_CHANNEL_ID"

​
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,
    "termsAndConditions": "Valid for new bookings only. Cannot be combined with other offers.",
    "icon": "discount-tag",
    "rank": 1
  },
  {
    "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",
    "minimumNights": 1,
    "discountMethod": "PERCENTAGE",
    "discountPercentage": 15.0,
    "maximumDiscountAllowed": 3000,
    "status": "ACTIVE",
    "type": "EARLY_BOOKER",
    "earlyBookerValueInDays": 30,
    "nonRefundable": false,
    "clubbed": true,
    "rank": 2
  }
]

​
Response Fields

FieldTypeDescription
idstringUnique identifier for the promotion
codestringPromotion code that guests can apply
titlestringDisplay title of the promotion
descriptionstringDetailed description
startDateTimestring (datetime)When the promotion becomes available for booking
endDateTimestring (datetime)When the promotion expires
stayStartDatestring (date)Earliest check-in date the promotion applies to
stayEndDatestring (date)Latest check-out date the promotion applies to
maximumUsageLimitintegerMaximum number of times the promotion can be redeemed
usageCountintegerNumber of times already redeemed
minimumNightsintegerMinimum stay length required
maximumNightsintegerMaximum stay length the promotion covers
discountMethodstringPERCENTAGE or FLAT
discountTypestringType of discount applied
targetstringWhat the discount applies to (e.g., ROOM, TOTAL)
discountAmountintegerFlat discount amount (when discountMethod is FLAT)
discountPercentagenumberPercentage discount (when discountMethod is PERCENTAGE)
maximumDiscountAllowedintegerMaximum discount cap for percentage-based discounts
minimumBookingAmountintegerMinimum booking amount required
statusstringACTIVE, INACTIVE, or EXPIRED
typestringPromotion category (see Promotion Types below)
nonRefundablebooleanWhether bookings using this promotion are non-refundable
weekendOnlybooleanApplies only on weekends
weekdayOnlybooleanApplies only on weekdays
clubbedbooleanCan be combined with other promotions
lastMinuteUnitstringTime unit for last-minute offers (HOURS or DAYS)
lastMinuteValueintegerTime value for last-minute eligibility
earlyBookerValueInDaysintegerMinimum days in advance for early booker offers
freeNightsintegerNumber of free nights (for free-night promotions)
termsAndConditionsstringTerms and conditions text
iconstringIcon identifier for display
rankintegerDisplay priority (lower = higher priority)
blackoutDatesobjectDates when the promotion is not applicable
checkinBlackoutDatesobjectCheck-in dates when the promotion is not applicable
ruleobjectAdditional rules and conditions

​
Promotion Types

TypeDescription
COUPONCode-based discount that guests can apply at checkout
EARLY_BOOKERDiscount for bookings made a certain number of days in advance
LAST_MINUTEDiscount for bookings close to the check-in date
FREE_NIGHTOffers free nights (e.g., “Stay 3, Pay 2”)
BASICStandard promotion without special conditions

​
Authentication

All requests must include the following headers:
  • Api-Key: Your API key for authentication
  • Channel-Id: Identifier for the channel making the request

​
Error Handling

The API returns standard HTTP status codes:
  • 200: Success
  • 401: Unauthorized
  • 404: Property not found
  • 500: Internal Server Error