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.

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.

How Promotions Affect Departures

Promotions are tightly coupled with Departures. In the majority of cases, a Promotion will be displayed in-line within the Departure object, within its price_bands. To highlight the primary scenarios and ones you should consider, we’ve provided the following table:

Promotions & Departures
Configuration Effect
Promotion is active and assigned to specific tour dossiers. Promotion is represented in-line in departure resource pricing to departures applicable to promotion configuration
Promotion has APPLY_AUTOMATICALLY flag Promotion is represented in-line in departure resource pricing.
Promotion sale date has begun or ended Promotion is added or removed from departure resource representation respectively
Promotion is assigned a limited set of currencies. Promotion is applied to departure resource repsentation for applicable price bands
Promotion is exclusive to an agency or agencies. Promotion is not represented within departure resource and must be discovered through /agencies/{id}/promotions endpoint.

Of course, in all cases, webhooks are delivered for changes to the representation of the departure and promotion resources.

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/