Promotions Overview

Create and manage promotional campaigns with discount codes

The Promotions API allows you to create and manage promotional campaigns with discount codes for your booking engine. Promotions support various discount types including percentage off, fixed amounts, and more.

Key concepts

Promotions

A promotion defines the discount rules and constraints:

• Type: The kind of discount (percentage, fixed amount, BOGO, bundle, tiered, free shipping, gift with purchase)
• Scope: What the promotion applies to (all products, specific products, categories, collections, or departures)
• Value: The discount amount or percentage
• Validity period: When the promotion is active
• Usage limits: Maximum total uses or per-customer limits

Promotion codes

Codes are the actual strings customers enter to redeem a promotion:

• Each promotion can have multiple codes
• Codes can have their own validity periods and usage limits
• Codes are automatically uppercased for case-insensitive matching

Scopes required

Endpoint	Scope
List, get, validate	marketing:read
Create, update, delete, redeem	marketing:write

Promotion types

Type	Description
percentage	Percentage discount off the order
fixed_amount	Fixed monetary discount
bogo	Buy one get one free
bundle	Bundle discount
tiered	Tiered pricing based on quantity
free_shipping	Free shipping discount
gift_with_purchase	Free gift with purchase

Promotion scopes

Scope	Description
all_products	Applies to all products
specific_products	Only applies to listed product IDs
specific_categories	Only applies to listed category IDs
specific_collections	Only applies to listed collection IDs
specific_departures	Only applies to listed departure IDs

Validation flow

When validating a promotion code:

1. Code lookup: Find the code and check it’s active
2. Code validity: Check date range and usage limits
3. Promotion status: Verify parent promotion is active
4. Promotion validity: Check promotion date range and total usage
5. Order constraints: Verify minimum order value, currency, product eligibility
6. Customer limits: Check per-customer usage if customer ID provided
7. Calculate discount: Return the applicable discount amount