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.

Note

There can be multiple active Promotions applicable to a single Departure and are presented in order of “best” to “worst” value.
Promotions on the Departure are found in the rooms[].price_bands[].prices[].promotions[] list object.
You cannot apply more than one promotion to a service.

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.
Promotion is exclusive to a specific region (e.g. UK Only)	Promotion is not represented within departure resource and must be discovered through `/agencies/{id}/promotions` endpoint. This list view takes into account the countries associated to the agency in relationship with G Adventures.

In all cases, webhooks are delivered for changes to the representation of both 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 – be applied to the booked service(s) automatically.

You can apply the promotion when creating the service, as per below. It is good practise to check the validity of the promotion using the start/finish dates. Attempting to apply an Inactive Promotion – or to a Departure that is out of the product-date range – will fail and we’ll return an error in that instance.

In the instance where multiple Promotions are available – and if the applied promotion is not included as part of the payload to create the departure service and one of those promotions has the APPLY_AUTOMATICALLY flag, G will automatically add that promotion to the service.

{
    "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 were not `Confirmed` prior to the `sale_finish_date` of the Promotion. (i.e. If the service was created on `Option` without the promotion, it cannot be retroactively applied if the service was not `Confirmed` during the Promotion’s `ACTIVE` period.
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 the NO_OPTIONS flag¶

A promotion with this flag CAN be applied to a Departure Service while it’s in the Option status and the promotion is on sale (active). The promotion CANNOT be applied retroactively, after the Promotion sale finish date, if the Departure Service was NOT “Confirmed” while the Promotion was on Sale.

Scenarios where it cannot be applied

Departure Service is created (without the promotion), while the Promotion is on Sale and is in an “Option” status
Promotion Sale finishes
Departure Service is “Confirmed” after the Promotion sale finishes
NO_OPTIONS as a business rule means the Promotion cannot be applied retroactively to a service

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.

When a promotion expires or is not active, it will not show when the Departure is queried.

Only “public” Promotions will appear in the Departures resource - so if an agency has an exclusive promotion that applies only to them - that is found via the agencies/{id}/promotions

Searching for Departures with Promotions¶

To search for departures that have applicable promotions, we can use the following query parameter when making the request: rooms.price_bands.prices.promotions__notnull=1.

e.g. https://rest.gadventures.com/departures/?rooms.price_bands.prices.promotions__notnull=1

This will return “ALL” departures that have some public, active (on sale) promotion. It is good practice to further refine the query by including the following parameters

**Recommended** parameters:¶
`availability.status=AVAILABLE`	Returns only those departures available to be booked
`start_date__gt={yyyy-mm-dd}`	Ideally the “current” or some future date to ensure past departures are not returned (e.g. 2024-04-22)

**Optional** parameters:¶
`order_by=start_date`	To order the results by the departure start date
`tour_dossier.id={tour_dossier_id}`	To filter results for a particular tour dossier
`booking_companies.id=1`	Include the relevant Booking Company ID if your API Key has access to content for multiple booking_company.
`start_date__lt={iso-date}`	To restrict the range of departures to a specific date range (use it together with `start_date__gt` to ensure past departures are not returned).

NOTE: for more information on searching, see Searching the G API.

An example query for AVAILABLE departures occuring after some start_date (using “2024-04-22” relative to when this document has been updated) that have Promotions would look like:

?rooms.price_bands.prices.promotions__notnull=1&availability.status=AVAILABLE&start_date__gt=2024-04-22

XML Schema: - promotions.xsd

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 & Times.
date_last_modified	Datetime	The time when the resource was last modified, in the standard Dates & Times.
promotion_code required	String	A unique code for this promotion.
booking_companies read-only	Field	The booking_company that own this promotion, and are in charge of its inventory and sale.
id read-only	String
href read-only	Field
name read-only	String	Company name
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 & Times.
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 & Times.
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 & Times.
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 & Times.
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 & Prices.
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/¶