Promotions

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:

On this page