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.

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.

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 & 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 services 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 services, 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 services, 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 services, 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 services, 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 services.

  • NO_OPTIONS: the promotion can only be applied to a confirmed services.

  • APPLY_AUTOMATICALLY: the promotion is applied automatically when a services 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/