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/