Skip to main content

​
Introduction

Promotions allow you to offer discounts on listings within your workspace. A promotion defines a discount percentage, an active date range, and optionally a coupon code. You can assign specific listings to a promotion, either individually or in bulk by integration account.

​
Creating a Promotion

To create a promotion, you need to provide:
  • name — A unique name for the promotion within your workspace
  • discountPercentage — The discount percentage (0-100) applied to listing prices
  • startDate and endDate — The period during which the promotion is visible/active
  • bookingPeriodStart and bookingPeriodEnd — The date range for which bookings can use this promotion
  • thumbnailURL — A URL for the promotion’s thumbnail image
Optional fields:
  • description — A description of the promotion
  • city — Geographic scope for the promotion
  • couponCode — A unique coupon code that guests can use to apply the promotion
{
  "name": "Summer Sale 2025",
  "description": "20% off all beachfront properties",
  "discountPercentage": 20,
  "startDate": "2025-06-01",
  "endDate": "2025-08-31",
  "bookingPeriodStart": "2025-06-01",
  "bookingPeriodEnd": "2025-08-31",
  "thumbnailURL": "https://example.com/summer-sale.jpg",
  "couponCode": "SUMMER20"
}

​
Date Validation

The following rules apply to promotion dates:
  • startDate must be before endDate
  • bookingPeriodStart must be before bookingPeriodEnd
  • startDate and bookingPeriodStart cannot be in the past

​
Assigning Listings

Once a promotion is created, you need to assign listings to it. There are two approaches:

​
Individual Assignment

Assign specific listings by providing an array of listing IDs: 
PUT /api/v1/promotions/{promotionId}/listings/assign

{
  "listingIDs": [
    "listing-uuid-1",
    "listing-uuid-2"
  ]
}
Duplicate assignments are automatically skipped.

​
Bulk Assignment by Integration Account

Assign all active listings from one or more integration accounts: 
PUT /api/v1/promotions/{promotionId}/integration-account/assign

{
  "integrationAccountIDs": [
    "account-uuid-1",
    "account-uuid-2"
  ]
}
This assigns all active listings under the specified integration accounts to the promotion.

​
Unassigning Listings

Similarly, you can unassign listings individually or in bulk:
  • Individual: PUT /api/v1/promotions/{promotionId}/listings/unassign with an array of listing IDs
  • By Integration Account: DELETE /api/v1/promotions/{promotionId}/integration-account/unassign with an array of integration account IDs

​
Viewing Promotion Listings

To see which listings are assigned to a promotion: 
GET /api/v1/promotions/{promotionId}/listings
This returns the listings with basic details including name, description, thumbnail, location, and bedroom/bathroom counts.

​
Promotion Status

Promotions are created with an ACTIVE status. You can update a promotion’s status to INACTIVE to disable it without deleting it. When listing promotions, use the includeInactive query parameter to include inactive promotions in the results: 
GET /api/v1/promotions?includeInactive=true

​
How Promotions Affect Pricing

When a promotion is applied to a listing, the discountPercentage is factored into the pricing calculations for search results, quotes, and reservations. The discount appears as a promotionDiscount in the price modifications breakdown. When creating a reservation, you can pass the promotionID to apply the promotion discount. The system validates that the promotion is active and the listing is included in the promotion.

​
API Reference

For detailed API documentation, refer to the following endpoints: