> ## Documentation Index > Fetch the complete documentation index at: https://docs.elivaas.com/llms.txt > Use this file to discover all available pages before exploring further. # Promotions - Retrieve ## 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 ```bash theme={null} 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](#promotion-object) 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](#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 ```json theme={null} [ { "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. |