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.

The 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": {
        "id": PROMOTION_ID
    }
}

Reference our Creating Your First Booking tutorial on how to create a Departure Services resource

Promotion Flags

As Promotions can be complex, we have provided this table to further elaborate what is displayed in the flags attribute on each Promotion.

Promotion Flags
Flag Effect
APPLY_AUTOMATICALLY Promotion is applied automatically when a departure is booked matching its criteria. Thus, you do not need to include the reference to the Promotion in any payload
NO_OPTIONS Promotion may not be applied to services which are being booked as Option
NOT_ACTIVE Promotion is no longer active and thus, cannot be applied. This is refreshed once an hour (EST/EDT Timezone)
ACTIVE Promotion is active and can be applied. This is refreshed once an hour (EST/EDT Timezone)
AGENCY_EXCLUSIVE Promotion is exclusive to one or more agencies. If your application can view this, it means the promotion is exclusive to your agency.
EXCLUDE_CLOSED_GROUP At times, departures are closed for private groups. This flag identifies that the Promotion cannot be applied to this closed groups.

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

Name Type Description
id read-only String  
href read-only Field  
name required String The name of this promotion.
date_created Datetime The time when the resource was created, in the standard dates-time.
date_last_modified Datetime The time when the resource was last modified, in the standard dates-time.
promotion_code required String A unique code for this promotion.
discount_amount required Decimal The fixed discount amount to be subtracted from the price of any product.
discount_percent required Decimal The discount percent to be applied to the price of any products associated with the promotion. For example, “10.00” represents a 10% discount while “0.50” represents a 0.5% discount.
commission_rate required Decimal The commission rate for this promotion. If not NULL, this will override the default commission rate on the product for which the promotion is applied.
min_travellers required Integer The minimum number of travellers on a booked product service for which this promotion can be applied.
sale_start_date required Date The earliest date (starting 00:01 EST on this day) this promotion can be applied to a booked service, in the standard dates-time.
sale_finish_date required Date The date on which this promotion expires, and can no longer be applied to a booked service, in the standard dates-time.
sale_start_datetime required Datetime The earliest date and time in UTC on which this promotion can be applied to a booked service, in the standard dates-time.
sale_finish_datetime required Datetime The date and time in UTC on which this promotion expires, and can no longer be applied to a booked service, in the standard dates-time.
product_start_date required Date For seasonal products, an inclusive date range is specified in the ‘start_date’ and ‘finish_date’ fields. When a promotion is associated with a seasonal product, this field indicates the earliest date for which the promotion is applicable.
product_finish_date required Date For seasonal products, an inclusive date range is specified in the ‘start_date’ and ‘finish_date’ fields. When a promotion is associated with a seasonal product, this field indicates the lates date for which the promotion is applicable.
terms_and_conditions required String The terms and conditions for the promotion.
currencies required List A list of currencies for which the promotion is applicable, The currency ISO code, in the standard currencies.
room_codes required List A list of departure room codes for which the promotion is applicable. If not NULL, each value relates to the ‘code’ field in the ‘rooms’ data of a departure resource (i.e. the promo is only applicable to specific rooming options).
flags required List

A list of codes that, when present, require special considerations when applying this promotion to a booked service.

  • NO_OPTIONS: the promotion can only be applied to a confirmed service.
  • APPLY_AUTOMATICALLY: the promotion is applied automatically when a service is booked for a product that is associated with the promotion.
  • MAX_USES: the promotion has reached its maximum number of uses and can no longer be applied.
  • AGENCY_EXCLUSIVE: The promotion is exclusive to your agency.
products required Field A list of products that are associated with the promotion (i.e. promotion can be applied to these products).
  • id read-only
String  
  • href read-only
Field The target URI for this resource. href corresponds with the Target IRI as defined in Web Linking (RFC 5988).
  • type required
String The type of this resource.
  • sub_type required
String The product category: Tour, Hotel, Transfer, Product

Get a Promotion

GET /promotions/(string: promotion_id)

List Public Promotions

GET /promotions/