Promotions

This resource represents a discount on a product. The following product resources can have associated promotions: departure, accommodation, transport, and activity. Promotions can be a fixed amount or percent. A promotion always has a sale start and finish date, as well being associated with specific currencies. Terms and conditions are always listed for a promotion. A unique promotion code is often used for reference.

Last minute promotions have the “flag” APPLY_AUTOMATICALLY. This means that the “promotion_code” does not need to be explicitly passed when booking the product service. The discount will automatically be applied, so that the promotional price is reflected.

The nested “promotions” list that appears in a “prices” object of a departure, ONLY contains last minute promotions, where as both last minute and agency-specific promotions appear in the agency promotions nested resource (/agencies/{id}/promotions).

Additionally, it is important to capture promotions.updated webhooks in order to ensure associated products have applicable promotions applied. You can iterate over the products key to obtain the affected resources.

This list view is meant as the root for discovering promotions available to general public. No agency application key registration is necessary. This view is in reverse chronological order based on creation date and only lists promotions active at time of consumption.

Applying Promotions To Departure Services

If the promotion has the flag APPLY_AUTOMATICALLY, this promotion will – as the name suggests – apply to the booked service(s) automatically. Otherwise, you may apply the promotion when creating a service, like so:

{
    "booking": { "id": BOOKING_ID },
    "product": { "id": PRODUCT_ID },
    "customers": [
        { "id" : CUSTOMER_ID }
    ],
    "applied_promotion": {
        "promotion_code": PROMOTION CODE
    }
}

Understanding sale and product dates

You will notice the Promotion resource has a couple of pairs of attributes around start and finish dates. They are: sale_start_date, sale_finish_date, and product_start_date, product_finish_date.

It’s important to understand how these affect the products listed within the resource. The sale_start_date and sale_finish_date pair identify when the promotion can be applied. The promotion cannot be applied unless the current date is between those two days.

Along side this, there are product_start_date and product_finish_date, which narrow down what products are applicable for the promotion. For a promotion to be applicable to a product, the product’s start_date must fall between these two dates. (This is an inclusive date range)

To clarify this, an example might look like this:

{
    "sale_start_date": "2015-06-30",
    "sale_finish_date": "2015-07-31",
    "product_start_date": "2015-07-01",
    "product_finish_date": "2016-03-31"
}

First, this means that if the product’s start or finish date is outside of the product_[start|finish]_date, then the Promotion cannot be applied for that product. Additionally, the promotion must be applied between the sale_[start|finish]_date range, otherwise it will be handled as invalid.

XML Schema:

Fields

Get a Promotion

GET /promotions/(string: promotion_id)

List Public Promotions

GET /promotions/