Waitlist Configuration Guide

Complete Implementation & Configuration Documentation

This guide provides comprehensive instructions for configuring and using the Waitlist feature in Kaptio. Waitlists allow customers to express interest in sold-out departures or specific cabin types, enabling your team to capture demand and fulfill requests when inventory becomes available.

What is Waitlist?

The Waitlist feature in Kaptio allows reservation consultants to capture customer interest for sold-out packages, specific departures, or cruise cabin types. When a customer can’t book their preferred option, they can join a waitlist and be notified when inventory becomes available.

Key Capabilities

Package Search Integration: Join waitlist directly from Package Search when departures are sold out
Booking Wizard Integration: Waitlist option available during the booking flow
Multi-Room Support: Single waitlist request can include multiple rooms with different configurations
Cruise Cabin Waitlists: Track interest in specific cabin types for cruise packages
Passenger Tracking: Store up to 4 passenger contacts per waitlist request
Availability Monitoring: Track last known availability status and when it was checked
Comments: Capture additional customer requirements or preferences

When to Use Waitlist

Sold-Out Departures: Capture demand when popular departures reach capacity
Limited Inventory: Allow customers to queue for specific cabin categories on cruise packages
Demand Analysis: Understand which packages and departures have excess demand
Proactive Sales: Contact waitlisted customers immediately when inventory becomes available
Waitlist Reporting: Report on unfulfilled demand to inform product decisions

The Waitlist feature is integrated into the Package Search and Booking Wizard components. Understanding how it fits into the broader architecture helps with configuration and troubleshooting.

How It Works

┌─────────────────────────────────────────────────────────────────────────┐
│                        Package Search                                    │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  User searches for packages and departures                       │    │
│  │  → Departure shows "Sold Out" or limited availability            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        Booking Wizard                                    │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  User selects passengers and rooms                               │    │
│  │  → "Join Waitlist" button appears in Summary                     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    Waitlist Comment Modal                                │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  User adds optional comments per room                            │    │
│  │  → Confirms waitlist creation                                    │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    WaitlistService.cls (Apex)                            │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Creates WaitlistRequest__c record                               │    │
│  │  Creates WaitlistRequestItem__c records for each cabin type      │    │
│  │  Uses Unit of Work pattern with transaction safety               │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

Key Components

Component	Purpose	Location
lwcBookingWizardSummaryWaitlist	Displays waitlist summary in Booking Wizard with “Join Waitlist” button	Lightning Web Component
lwcBookingWizardWaitlistCommentModal	Modal for adding comments when joining waitlist	Lightning Web Component
WaitlistService.cls	Apex service handling waitlist creation and business logic	Apex Class
WaitlistDto.cls	Data transfer objects for waitlist operations	Apex Class
WaitlistRequest__c	Custom object storing waitlist requests	Custom Object
WaitlistRequestItem__c	Custom object storing individual waitlist items (cabin types)	Custom Object

Integration Dependency

The Waitlist feature is tightly integrated with Package Search and Booking Wizard. Ensure both features are properly configured before enabling waitlist functionality.

Before configuring Waitlist, ensure the following are in place:

●

Package Search Configured: Package Search must be working correctly with departures displaying availability status

●

Booking Wizard Enabled: The Booking Wizard integration should be active on your Package Search configuration

●

Package Departures: Packages must have departures configured with inventory/capacity settings

●

Channels Configured: Sales channels must be set up with appropriate pricing

●

Contacts: Customer contacts should be available for passenger assignment

●

For Cruise Packages: Price Categories (cabin types) must be configured on cruise components

Minimum Release

The Waitlist feature was introduced in a later Kaptio release. Contact your Kaptio representative to confirm your org version supports this feature.

User Guide

The Waitlist feature captures customer interest when their preferred package, departure, or cabin type is unavailable. This enables proactive sales when inventory becomes available.

When Waitlist Appears

Sold-Out Departures — When a departure has no available inventory, users can join a waitlist to be contacted when spaces open up due to cancellations or inventory releases.

Specific Cabin Types (Cruise) — For cruise packages, customers may want a specific cabin category that’s currently sold out. They can waitlist for that cabin type while other categories may still be available.

Limited Availability — When remaining inventory is less than the requested party size, customers can join a waitlist for potential space increases.

Waitlist Status Values

Status	Description
Active	Customer is actively waiting for availability (default status)
Cancelled	Customer no longer interested or request was withdrawn
Fulfilled	Inventory became available and customer was successfully booked

Last Known Availability

Each waitlist item tracks the availability status when the waitlist was created:

Availability	Description
Available	Inventory was available at time of waitlist creation (rare edge case)
Sold Out	No inventory available when waitlist was created
Departure Passed	The departure date has passed (for historical reference)

This section walks through the complete user flow for joining a waitlist from Package Search through the Booking Wizard.

Step-by-Step Flow

Search →
Select Departure →
Add with Options →
Configure Rooms →
Join Waitlist

1. Search for Package

User searches for packages in Package Search. Results show availability status for each departure.

2. Select a Sold-Out Departure

User selects a departure that shows “Sold Out” or limited availability. The system allows proceeding to capture the waitlist.

3. Launch Booking Wizard

User clicks “Add with Options” to launch the Booking Wizard, which displays the waitlist summary component instead of the standard booking summary.

4. Configure Rooms and Passengers

User configures the room setup and assigns passengers (contacts) to each room. For cruise packages, they select their preferred cabin types.

5. Join Waitlist

Click the “Join Waitlist” button in the summary panel
The comment modal opens, showing each room with assigned passengers
Add optional comments (special requests, preferences, etc.) for each room
Click “Confirm” to create the waitlist request

What Gets Captured

When a waitlist is created, the following information is stored: Account and Channel context Primary Contact Package Departure Room configuration (occupancy string) Up to 4 passenger contacts per room Cabin type preferences (for cruise packages) Last known availability status User comments

Once waitlist requests are created, they can be viewed, updated, and fulfilled through the Salesforce interface.

Viewing Waitlist Records

Navigate to the Waitlists tab in Salesforce (if added to your app)
Use list views to filter by status (Active, Fulfilled, Cancelled)
Click on a record to view full details

Waitlist Record Page

The Waitlist record page displays:

Highlights Panel: Key information at a glance
Details: All waitlist fields including Account, Contact, Departure, Occupancy
Waitlist Items: Related list showing each cabin type/item on the waitlist
Passenger Contacts: Up to 4 contacts associated with this waitlist

Fulfilling a Waitlist

When inventory becomes available:

Identify Active waitlist requests for the departure
Contact the customer to confirm they still want to book
Create a new booking through Package Search/Booking Wizard
Update the Waitlist Status to “Fulfilled”

Manual Fulfillment Process

Currently, waitlist fulfillment is a manual process. There is no automatic notification when inventory becomes available. Consider setting up reports or dashboards to monitor Active waitlists against available inventory.

Cancelling a Waitlist

If a customer no longer wants to be on the waitlist:

Open the Waitlist record
Change the Waitlist Status to “Cancelled”
Optionally update the Comments field with the cancellation reason
Save the record

For cruise packages with physical inventory (cabins), the waitlist feature tracks interest in specific cabin types or categories.

How Cruise Waitlists Work

Each cabin type selected in the Booking Wizard creates a separate Waitlist Item
The PriceCategory__c field on the item links to the specific cabin type
Multiple cabin types can be waitlisted in a single request
Each item tracks its own Last Known Availability and Last Checked timestamp

Displayed Information

In the Booking Wizard summary, cruise waitlists display:

Cabin Name: External name of the cabin type
Cabin Description: Short description of the cabin
Pricing: Price per person, quantity, and total (from the pricing details)
Passengers: List of passengers assigned to this room

Multi-Room Cruise Bookings

Each room in a multi-room cruise booking can have different cabin type preferences. The waitlist captures all rooms with their respective cabin selections in a single request.

Configuration Guide

The Waitlist feature requires minimal configuration as it is integrated into the existing Package Search and Booking Wizard components. However, there are several configuration points for customization.

Configuration Areas

App Settings: Global settings that affect waitlist behavior
Page Layouts: Configure which fields appear on Waitlist records
Permissions: Control who can create, view, and manage waitlists
Automation: Optional workflows, flows, or triggers for notifications
Reports & Dashboards: Monitor waitlist activity and demand

Out-of-the-Box Behavior

The Waitlist feature works with default settings:

Source is automatically set to “PackageSearch”
Status defaults to “Active”
Availability is captured at the time of waitlist creation
Up to 4 passengers can be associated per waitlist

The Waitlist feature uses two custom objects in a master-detail relationship.

WaitlistRequest__c (Parent)

Stores the overall waitlist request with customer and context information.

Field	Type	Description
`Name`	Auto-Number	Format: WR-{”{”+“00000”+”}“}
`Account__c`	Lookup	Related Account for this waitlist
`Channel__c`	Lookup	Sales Channel used during search
`Contact__c`	Lookup	Primary Contact for the waitlist
`PackageDeparture__c`	Lookup	The specific Package Departure being waitlisted
`Occupancy__c`	Text	Room configuration string (e.g., “1=2,0” for Room 1: 2 adults, 0 children)
`Comments__c`	Long Text Area	Customer comments and special requests
`SourceOfWaitlist__c`	Picklist	Where the waitlist was created (default: “PackageSearch”)
`WaitlistStatus__c`	Picklist (Global)	Active, Cancelled, or Fulfilled
`PassengerContact1__c`	Lookup	First passenger contact
`PassengerContact2__c`	Lookup	Second passenger contact
`PassengerContact3__c`	Lookup	Third passenger contact
`PassengerContact4__c`	Lookup	Fourth passenger contact

WaitlistRequestItem__c (Child)

Stores individual items (cabin types) within a waitlist request.

Field	Type	Description
`Name`	Auto-Number	Format: WRI-{”{”+“00000”+”}“}
`WaitlistRequest__c`	Master-Detail	Parent Waitlist Request
`PriceCategory__c`	Lookup	The Price Category (cabin type) being waitlisted
`Status__c`	Picklist (Global)	Active, Cancelled, or Fulfilled (inherits from WaitlistStatus)
`LastKnownAvailability__c`	Picklist	Available, SoldOut, or DeparturePassed
`LastChecked__c`	DateTime	When availability was last checked

Data Model Diagram

WaitlistRequest__c (Parent)
├── Account__c ────────────────────► Account
├── Channel__c ────────────────────► Channel__c
├── Contact__c ────────────────────► Contact (Primary)
├── PackageDeparture__c ───────────► PackageDeparture__c
├── PassengerContact1-4__c ────────► Contact (Passengers)
│
└── WaitlistItems__r (Child Related List)
    └── WaitlistRequestItem__c
        ├── PriceCategory__c ──────► Price_Category__c
        └── Status, Availability, LastChecked

There is one App Setting that affects waitlist behavior.

Enable Waitlist On Supplier Requests

Setting	Value
Field	`AppSettings__c.EnableWaitlistOnSupplierRequests__c`
Type	Checkbox
Default	false
Description	If enabled, displays a Waitlist status on the supplier action page

How to Configure

Navigate to Setup → Custom Settings
Click Manage next to App Settings
Edit the org-default record or create a new one
Check or uncheck Enable Waitlist On Supplier Requests
Save

Supplier Action Page Integration

When enabled, the waitlist status becomes visible on supplier-facing pages, allowing suppliers to see pending demand for their inventory.

Configure page layouts to display relevant waitlist information for your users.

Waitlist Request Layout

Customize the WaitlistRequest__c - Waitlist Layout to include:

Key Information Section: Account, Contact, Channel, Package Departure
Status Section: Waitlist Status, Source of Waitlist
Passengers Section: PassengerContact1-4 fields
Details Section: Occupancy, Comments
Related Lists: Waitlist Items

Waitlist Item Layout

Customize the WaitlistRequestItem__c - Waitlist Item Layout to include:

Item Details: Price Category, Status, Last Known Availability, Last Checked
Parent Reference: Waitlist Request (auto-included as master-detail)

Lightning Record Page

The default WaitlistRecordPage flexipage is configured with:

Highlights Panel
Related Lists (Waitlist Items)
Detail Panel

Customization Options

Consider adding custom components to the Lightning Record Page for: Departure availability quick check Quick action to create booking when inventory available Related waitlists for the same departure

Configure object and field-level security to control access to waitlist functionality.

Object Permissions

Object	Sales Users	Operations	Admin
WaitlistRequest__c	Create, Read, Edit	Read, Edit	All
WaitlistRequestItem__c	Create, Read, Edit	Read, Edit	All

Field-Level Security

Key fields to configure visibility:

WaitlistStatus__c: Editable by all users who need to fulfill/cancel waitlists
Comments__c: Visible and editable for sales and operations
LastKnownAvailability__c: Read-only (set by system)
LastChecked__c: Read-only (set by system)

Recommended Permission Set

Create a permission set Waitlist_User with:

Read/Create/Edit access to WaitlistRequest__c
Read/Create/Edit access to WaitlistRequestItem__c
Field-level access to all standard fields
Tab visibility for Waitlists (if tab is created)

Consider implementing automation to enhance the waitlist workflow.

Recommended Automations

1. New Waitlist Email Notification — Send confirmation email to customer when waitlist is created.

2. Waitlist Assignment — Automatically assign new waitlists to the account owner or a queue.

3. Departure Passed Update — Automatically update WaitlistRequestItem status when departure date passes.

4. Fulfillment Notification — Notify sales team when inventory becomes available for waitlisted departures.

Custom Development Required

The automations above require custom development (flows, triggers, or scheduled jobs). They are not included out-of-the-box with the Waitlist feature.

Test Waitlist Creation

☐ Search for a package with sold-out departures

☐ Select a sold-out departure and launch Booking Wizard

☐ Configure rooms and assign passengers

☐ Click “Join Waitlist” button

☐ Add comments in the modal

☐ Confirm and verify waitlist record created

Verify Waitlist Data

☐ Open the created Waitlist record

☐ Verify Account, Contact, Channel are correct

☐ Verify Package Departure is linked

☐ Verify Occupancy string is populated

☐ Verify Comments are saved

☐ Verify Passenger Contacts are populated

☐ Verify Status is “Active”

☐ Verify Waitlist Items are created (for cruise packages)

Test Status Changes

☐ Change Waitlist Status to “Cancelled”

☐ Change Waitlist Status to “Fulfilled”

☐ Verify status changes are saved correctly

Test Cruise Cabin Waitlist

☐ Search for a cruise package

☐ Select a cabin type that is sold out

☐ Create waitlist and verify cabin type is captured

☐ Verify Waitlist Items show correct Price Category

Operational Best Practices

Regular Review: Set up a daily or weekly process to review Active waitlists against current inventory
First-Come-First-Served: When fulfilling waitlists, use Created Date to prioritize earlier requests
Clear Communication: Use Comments field to capture customer preferences and special requests
Status Hygiene: Keep statuses updated - cancel waitlists that are no longer needed

Reporting Recommendations

Active Waitlists by Departure: Identify departures with high demand
Waitlist Fulfillment Rate: Track percentage of waitlists successfully converted to bookings
Average Wait Time: Measure time from waitlist creation to fulfillment
Demand Analysis: Use waitlist data to inform decisions about adding capacity

Data Management

Archive Old Waitlists: Consider archiving fulfilled/cancelled waitlists older than a certain period
Departure Passed Cleanup: Automatically update status when departure dates pass
Duplicate Prevention: Consider validation rules to prevent duplicate waitlists for same contact/departure

Common Issues

Join Waitlist button not appearing — Possible causes:

Waitlist creation fails — Possible causes:

Passenger contacts not saved — Possible causes:

Waitlist Items not created (cruise packages) — Possible causes:

Cannot change Waitlist Status — Possible causes:

Appendix

Pre-Implementation

☐ Verify Package Search is configured and working

☐ Verify Booking Wizard is enabled and functioning

☐ Confirm packages have departures with inventory settings

☐ Confirm your Kaptio release supports Waitlist feature

Permissions Setup

☐ Configure object permissions for WaitlistRequest__c

☐ Configure object permissions for WaitlistRequestItem__c

☐ Set field-level security for all relevant fields

☐ Create permission set for waitlist users (optional)

Page Layouts

☐ Customize Waitlist Request page layout

☐ Customize Waitlist Item page layout

☐ Review Lightning Record Page for Waitlist

App Settings

☐ Configure EnableWaitlistOnSupplierRequests if needed

Optional Enhancements

☐ Add Waitlist tab to app navigation

☐ Create list views for waitlist management

☐ Set up reports for waitlist monitoring

☐ Build dashboard for waitlist analytics

☐ Implement automation for notifications (optional)

Testing

☐ Complete functional testing checklist

☐ Test cruise package waitlist (if applicable)

☐ User acceptance testing with sales team

WaitlistRequest__c Fields

API Name	Label	Type	Required
`Account__c`	Account	Lookup(Account)	No
`Channel__c`	Channel	Lookup(Channel__c)	No
`Contact__c`	Contact	Lookup(Contact)	No
`PackageDeparture__c`	Package Departure	Lookup(PackageDeparture__c)	No
`Occupancy__c`	Occupancy	Text(255)	No
`Comments__c`	Comments	Long Text Area(32768)	No
`SourceOfWaitlist__c`	Source of Waitlist	Picklist	No
`WaitlistStatus__c`	Waitlist Status	Picklist (Global Value Set)	No
`PassengerContact1__c`	Passenger Contact 1	Lookup(Contact)	No
`PassengerContact2__c`	Passenger Contact 2	Lookup(Contact)	No
`PassengerContact3__c`	Passenger Contact 3	Lookup(Contact)	No
`PassengerContact4__c`	Passenger Contact 4	Lookup(Contact)	No

WaitlistRequestItem__c Fields

API Name	Label	Type	Required
`WaitlistRequest__c`	Waitlist Request	Master-Detail(WaitlistRequest__c)	Yes
`PriceCategory__c`	Price Category	Lookup(Price_Category__c)	No
`Status__c`	Status	Picklist (Global Value Set)	No
`LastKnownAvailability__c`	Last Known Availability	Picklist	No
`LastChecked__c`	Last Checked	DateTime	No

The Waitlist feature uses Apex services for programmatic access.

WaitlistService

Main service class for waitlist operations.

Constants

public static final String WAITLIST_SOURCE_PACKAGE_SEARCH = ‘PackageSearch’; public static final String WAITLIST_STATUS_ACTIVE = ‘Active’;

transformInputData

Transforms input request data into waitlist DTOs.

`public static List transformInputData(WaitlistDto.CreateWaitlistsRequest input)`

createWaitlists

Creates waitlist records with transaction safety (rollback on error).

public static Map createWaitlists(List waitlistsData)

// Returns: // { ‘status’: ‘success’, ‘records’: List } // OR // { ‘status’: ‘ERROR’, ‘message’: ‘Error description’, ‘exception’: Exception }

WaitlistDto

Data transfer object classes for waitlist operations.

Key Inner Classes

CreateWaitlistsRequest - Input structure containing account, channel, contact, occupancy, departure info
CreateWaitlistsDto - Container for multiple waitlist requests
CreateWaitlistDto - Individual waitlist with cabin types, contacts, room ID, comment
WaitlistItemDto - Individual item with price category, status, availability
WaitlistItemAvailabilityDto - Availability info with cabin type, units available, bookable flag

Key Methods

assignBaseContext() - Sets base context (account, channel, contact, departure) from request
parse() - Converts DTO to WaitlistRequest__c SObject
withPassengerContacts(List) - Sets up to 4 passenger contacts
setPassengerContactId(Integer, Id) - Sets individual passenger contact (validates index 1-4)

Package Search Guide - Complete guide to Package Search
Booking Wizard User Guide - Configuration and usage of Booking Wizard

Source Code References

Key files in the kaptiotravel repository:

sfdx-source/kaptio-travel/main/classes/WaitlistService.cls
sfdx-source/kaptio-travel/main/classes/WaitlistDto.cls
sfdx-source/kaptio-travel/main/objects/WaitlistRequest__c/
sfdx-source/kaptio-travel/main/objects/WaitlistRequestItem__c/
sfdx-source/kaptio-travel/packages/lwc/lwcBookingWizardSummaryWaitlist/
sfdx-source/kaptio-travel/packages/lwc/lwcBookingWizardWaitlistCommentModal/

Occupancy String Format

The Occupancy__c field stores room configuration as a string. Format:

RoomNumber=Adults,Children;RoomNumber=Adults,Children

Examples: “1=2,0” // Room 1: 2 adults, 0 children “1=2,0;2=2,1” // Room 1: 2 adults; Room 2: 2 adults + 1 child “1=1,0;2=1,0” // Two single-occupancy rooms

Need Help?

Contact your Kaptio representative or visit the Kaptio Community for additional support.