Promotions¶

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:

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.

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

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

Get a Promotion

GET /promotions/(string: promotion_id)¶

List Public Promotions

GET /promotions/¶