Promotions in Booking Wizard

Overview

This guide covers how promotions work within the Booking Wizard flow — from Package Search through to Booking Overview and itinerary creation. It is aimed at implementation teams scoping promotions for customers who use Booking Wizard as their primary booking interface.

If you’re working with a customer who wants discounts, promo codes, or automatic pricing adjustments in Booking Wizard, start here. The guide walks through what’s supported today, how the two price summaries differ, what happens at each stage of a new booking, how promotions behave on modify, and where the current gaps are relative to industry expectations.

By the end you should be able to confidently scope a promotions implementation, identify what works out of the box, and flag what needs workarounds or custom development.

Supported Promotion Types

Two promotion types currently work in Booking Wizard:

Standard Promotions (Automatic)

Standard promotions apply automatically when conditions are met. The Booking Wizard reads the promotion assignment on the Package and applies the discount if the booking dates and passenger configuration match the promotion’s eligibility rules.

There is no customer interaction required — the discount appears in the price summary as soon as the conditions are satisfied. This is the most common promotion type for early-bird discounts, seasonal offers, and date-range-based price reductions.

Promo code promotions require the customer to enter a code during the booking flow. The system validates the code against the promotion record, checks eligibility (dates, passenger configuration, channel), and applies the discount if everything passes.

The promo code input field appears in the Booking Wizard’s price summary panel. The validation happens in real time — the customer sees immediate feedback on whether the code is valid and the updated price.

Free night offers (cheapest / most expensive night)

Promotions can discount the cheapest night or the most expensive night of a multi-night accommodation stay. That only works when the accommodation component creates one itinerary item per night per room — see Free night promotions — setup placeholder at the end of this guide for prerequisites and the space reserved for full configuration steps (pending review).

Discount Calculation Methods

Both promotion types support:

Fixed-value discounts — a flat amount deducted from the total (e.g., $200 off)
Per-person fixed discounts — a flat amount per passenger (e.g., $50 off per person)

Percentage-based discounts are NOT currently supported in Booking Wizard. This is a known limitation. If a customer requires percentage discounts, see the Opportunities and Gaps section for workaround options.

The Two Price Summaries

This is one of the most important concepts for implementation teams to understand. There are two different price summaries in the customer journey, and they calculate differently.

Package Search Expanded Details

The price summary shown when a customer expands a package in search results is indicative. It is calculated from the Package’s base price plus any automatic promotions that apply at the package level.

This summary:

Reflects automatic promotions based on the Package’s promotion assignment
Does NOT include promo code discounts (the customer hasn’t entered a code yet)
Does NOT account for specific passenger configurations (it uses default assumptions)
Is designed for browsing — it gives a ballpark price to help customers compare options

Booking Wizard Price Summary

The price summary inside the Booking Wizard is authoritative. This is the real calculation that includes all applicable promotions — both automatic and promo code — evaluated against the actual passenger and room configuration.

This summary:

Includes automatic promotions re-evaluated against the real booking parameters
Includes promo code discounts after the customer enters and validates a code
Reflects the actual passenger count, room configuration, and dates
Is the price that creates the itinerary

Key point: If a customer sees a discounted price in Package Search but a different price in Booking Wizard, it’s usually because the Package Search summary is indicative and doesn’t include all promotion conditions. This is expected behaviour, not a bug. Help customers set expectations around this during implementation.

New Booking Flow

Promotions interact with seven stages of the new booking flow. Understanding what happens at each stage helps when debugging pricing discrepancies or explaining the customer experience.

Stage 1: Package Search

The customer searches for packages. Automatic promotions are reflected in the search results pricing — packages with active promotions show the discounted indicative price. Promo code promotions are not visible at this stage since there is no mechanism to enter a code in search.

Stage 2: Package Selection

The customer selects a package and sees the expanded details panel. This panel shows the indicative price summary including any automatic discounts from promotions assigned to the Package. The customer uses this to decide whether to proceed into the Booking Wizard.

Stage 3: Booking Wizard Opens

The Booking Wizard initialises with the selected package. At this point the system checks promotion eligibility against the channel configuration and the package’s promotion assignments. The initial price shown reflects automatic promotions but uses default passenger/room assumptions until the customer configures them.

Stage 4: Passenger & Room Configuration

The customer configures passengers and rooms. This is where per-person promotions become dynamic — the discount amount recalculates as passengers are added or removed. The price summary updates in real time to reflect the current configuration.

For per-person fixed discounts, the calculation is straightforward: discount amount × number of eligible passengers. Since promotions apply at the room level, the passenger count within each room drives the calculation.

If the customer has a promo code, they enter it in the input field within the price summary panel. The system validates the code in real time:

Checks the code exists and is active
Validates the code against the channel configuration
Checks date eligibility (booking context date (BCD) and/or travel date windows; BCD is resolved per room — see subsection below)
Checks passenger/room eligibility
If valid, applies the discount and updates the price summary immediately

If the code is invalid or ineligible, the customer sees an error message explaining why.

Stage 6: Price Summary Review

The authoritative price summary now shows all applicable discounts broken down as individual line items. The customer can see:

The base package price
Each automatic discount applied (with the promotion name)
The promo code discount (if applicable)
The final total after all discounts

This is the last review point before the customer commits to the booking.

Stage 7: Booking Overview / Itinerary Creation

The booking is created and promotions are written to the itinerary as discount line items. Each applied promotion creates a record linked to the itinerary, preserving the promotion name, discount type, and amount for reporting and downstream processing.

Modifying Existing Bookings

Promotions behave differently depending on type when a booking is modified through the Booking Wizard.

Automatic Promotions

Automatic promotions are re-evaluated on modify. The system checks the updated booking parameters (dates, passengers, rooms) against the promotion’s eligibility conditions. If the booking no longer meets the conditions — for example, the travel dates were changed to fall outside the promotion’s valid date range — the promotion is removed and the price adjusts accordingly.

This means a customer could lose a discount if they modify their booking. Implementation teams should make customers aware of this behaviour.

Promo code promotions remain applied unless explicitly removed. The code is stored on the itinerary record, and the system preserves the discount through modifications. The customer does not need to re-enter the code.

If the promo code’s eligibility conditions are no longer met after modification (e.g., the travel dates fall outside the code’s valid window), the behaviour depends on configuration — in most cases the discount is preserved to avoid a negative customer experience, but this should be validated during implementation.

Adding Services or Passengers

When services or passengers are added to an existing booking:

Per-person promotions may recalculate based on the new passenger count
New passengers may trigger additional discount eligibility
The promotion amount on the itinerary updates to reflect the new calculation

Room-Level Application

Promotions apply at the room level, not the individual passenger level. This is an important distinction when scoping:

A per-person discount calculates per passenger but applies to the room total
You cannot apply different promotions to different passengers within the same room
If a customer needs passenger-level granularity (e.g., different discounts for adults vs. children in the same room), this is a limitation — see the gaps table below

How the booking context date (BCD) is resolved for eligibility

When re-evaluating promotion eligibility in the Booking Wizard (e.g. on modify or when recalculating), the system does not simply use “the passenger booking date”. It resolves a Booking-Context Date (BCD) per room using the following precedence:

Transfer date → 2. Reinstate date → 3. Booking date → 4. Today’s date

Rule: as soon as at least one passenger in the room has a non-null value at a given precedence level, the BCD is the earliest of those values across all passengers in the room at that level. If no passenger has any of the three stamps (transfer, reinstate, or booking date), the BCD falls back to today’s date.

In other words, the system iterates over the precedence-ordered fields (transfer date, reinstate date, booking date); for the first field that has at least one non-null value across the room’s passengers, it takes the minimum (earliest) of those values as the BCD; if none of the three fields has any value, it uses today.

Resolving BCD for one room (pseudo-algorithm):

# Precedence: ① transferDate → ② reinstateDate → ③ bookingDate → ④ today
# Rule: as soon as a precedence level has ≥1 value, return the earliest of them

for field in [transferDate, reinstateDate, bookingDate]:
    stamps = [p[field] for p in roomPassengers if p[field] is not null]
    if stamps is not empty:
        return MIN(stamps)
return today

Travel Industry Expectations vs Current Limitations

Understanding where Kaptio’s Booking Wizard promotion capabilities align with — and diverge from — standard travel industry expectations helps set the right expectations during scoping.

Feature	Industry Expectation	Kaptio Today
Percentage discounts	Standard across most booking platforms	Not supported in Booking Wizard
Per-passenger discounts	Common for child/senior pricing tiers	Room-level only — discount calculates per person but applies at room level
Child pricing via promotions	Expected as a promotion type	Workaround: use child discount on Package pricing, not promotions
Stacking multiple promotions	Sometimes needed for loyalty + seasonal offers	One automatic + one promo code per booking
Package Search showing full discount	Expected to match final price	Indicative only — authoritative price is in Booking Wizard
Early-bird / last-minute auto-apply	Common across the industry	Supported via date-based promotion conditions

Percentage Discounts

The most commonly raised gap. Many travel operators express discounts as percentages (e.g., “15% off”). Booking Wizard currently only supports fixed-value and per-person fixed discounts. The workaround is to calculate the equivalent fixed amount and configure that, but this doesn’t scale well if package prices vary.

Child Pricing

The travel industry typically handles child discounts as a promotion or pricing rule. In Kaptio, the recommended approach is to configure child pricing directly on the Package pricing rather than using promotions. This gives more control and avoids the room-level limitation.

Promotion Stacking

Booking Wizard supports one automatic promotion plus one promo code promotion per booking. If a customer needs more complex stacking (e.g., a loyalty discount plus an early-bird discount plus a promo code), this requires custom development or a redesign of the promotion structure to consolidate into fewer promotions.

Opportunities and Gaps

Use this table during scoping conversations to quickly assess what’s achievable for a customer’s promotion requirements.

Area	Status	Scoping Recommendation
Fixed-value discounts	Supported	Standard approach — no custom work needed
Per-person fixed discounts	Supported	Configure on the promotion record; calculates per person, applies at room level
Promo code validation	Supported	Requires Channel configuration for the promo code to be validated against
Percentage-based discounts	Gap	Custom development required, or workaround with fixed amounts if package prices are uniform
Passenger-level granularity	Gap	Use room-level promotions; handle child pricing via Package configuration instead
Multi-promotion stacking	Limited	One automatic + one promo code per booking; discuss with customer if more complex stacking is needed
Modify flow preservation	Supported	Promo codes persist through modifications; automatic promotions re-evaluate against new booking parameters
Date-based auto-apply	Supported	Configure promotion conditions with valid date ranges for early-bird or last-minute offers
Channel-specific promotions	Supported	Promotions can be scoped to specific channels via configuration

Scoping tip: When scoping promotions for a new customer, start by mapping their existing promotion types to the supported/gap table above. This quickly identifies what works out of the box vs. what needs workarounds or custom development. Getting this mapping done early avoids surprises later in the project.

Minimum Night Stays

Minimum night stay rules control whether a price or discount applies based on the booking length (allocation). This is configured on pricing records, not on inventory — allocation minimums are a pricing-engine concern.

Where Minimum Night Stays Are Configured

There are two places where allocation minimums can be set:

Directly on the pricing record — Item_Price__c.AllocationMinimum__c is a numeric field (default 0) that specifies the minimum booking length for that price row to be selected. The pricing engine only matches a price if the booking’s allocation meets or exceeds this value. When the field is null it is enforced to 0 on save, meaning the price has no minimum stay restriction.
On a Business Rule linked to a pricing record or discount — BusinessRule__c.AllocationMinimum__c is described in the metadata as the “minimum value of allocation to include the Business Rule into the calculation price process.” Business Rules can also set an AllocationMaximum__c, creating an allocation range. When a Business Rule is linked to a price or a discount, the pricing engine evaluates the booking’s allocation against the rule’s range to decide whether that price or discount qualifies.

A pricing record cannot have both a Business Rule assignment and its own AllocationMinimum__c/QuantityMinimum__c values — the system enforces that these two mechanisms are mutually exclusive.

How Allocation Maps to Nights

In the Kaptio data model, “allocation” represents booking length. The Allocation__c field on Itinerary_Item__c is a text value such as “3 Nights” or “5 Days”. A companion formula field (AllocationDays__c) extracts the numeric portion — parsing “3 Nights” to 3 and “5 Days” to 5. When the pricing engine evaluates prices and discounts, it compares the booking’s allocation (this numeric value) against the minimum and maximum thresholds.

Interaction with the Booking Wizard

When a customer configures a booking in the Booking Wizard, the pricing engine runs the allocation check as part of price selection. If the booking length does not meet a price’s allocation minimum, that price row is silently excluded — the engine moves to the next matching price. There is no error message or validation warning shown to the customer. The same applies to discounts: if a discount’s Business Rule specifies an allocation minimum of 3 and the booking is for 2 nights, the discount does not apply and the customer sees the undiscounted price.

This means minimum night stay restrictions are invisible to the customer. They do not see “minimum 3 nights required” — they simply see the pricing that matches their booking configuration. Implementation teams should account for this during scoping: if a customer expects an explicit minimum-stay message in the Booking Wizard, that would require custom development.

Interaction with Promotions and Discounts

This is the key reason minimum night stays are relevant to promotions scoping. Discounts (which power promotions) can have Business Rules attached, and those Business Rules can include allocation range conditions. The DiscountService checks isDiscountAllocationApplicable — evaluating the discount’s Business Rule allocation range against the booking’s allocation — before applying the discount to the price calculation.

In practice this means:

A promotion can be configured to only apply for bookings of 3+ nights by linking a Business Rule with AllocationMinimum__c = 3 to the discount
A promotion can be restricted to a specific range (e.g., 3–7 nights) using both AllocationMinimum__c and AllocationMaximum__c on the Business Rule
If the booking length falls outside the range, the promotion’s discount is excluded from the price calculation — the customer sees no discount line item

The pricing engine sorts matched prices by AllocationMinimum__c descending, so more specific allocation-based prices (higher minimums) take precedence over generic ones. This ordering applies to both direct price minimums and Business Rule–linked prices.

Scoping Considerations

Scenario	Approach
Promotion applies only for 3+ night stays	Attach a Business Rule with `AllocationMinimum__c = 3` to the discount
Different pricing tiers by stay length (e.g., 1–2 nights vs 3–5 nights vs 6+ nights)	Use separate pricing records with appropriate `AllocationMinimum__c` values, or separate Business Rules
Customer wants an explicit “minimum stay” error message	Not supported out of the box — the pricing engine silently excludes non-matching prices. Custom development required
Promotional pricing for a specific stay range (e.g., 5–7 night packages only)	Use a Business Rule with both `AllocationMinimum__c` and `AllocationMaximum__c` on the discount

Note: ParameterizedRule is a separate concept — it belongs to the payment schedule engine (deposits, final balance, due dates) and is not related to minimum night stay logic.

Free Night Promotions (Cheapest / Most Expensive Night Free)

This section is a placeholder. Detailed setup instructions are pending review and will be added in a future update.

Free night promotions discount a specific night within a multi-night accommodation stay — either the cheapest night or the most expensive night. To use this promotion type, the accommodation component must have Create Item Per Night Per Room (CreateItineraryItemPerNightPerRoom__c) enabled. The promotion engine needs individual night line items to identify which night to discount. See Package Configuration — Day Range & Night Fields for details on this setting.

Setup steps, eligibility conditions, and worked examples will be documented here once the guide is reviewed.