Package Fundamentals

Overview

Every package in Kaptio — whether Anyday, Seasonal, or Fixed — shares a common foundation: components, component options, sort ordering, defaulting rules, categories, and access controls. These fundamentals are consistent across all departure types.

This guide covers the shared layer. The departure-type-specific guides (Anyday, Seasonal, Fixed) build on top of what is described here. Read this guide first if you are setting up any package for the first time.

Prerequisites

Before creating any package, ensure the following are in place:

Supplier services created for all services you plan to include (Supplier & Service Setup)
Price Categories and pricing configured on those services (Cost & Pricing Architecture)
Locations set up for start and end destinations (Location Setup Guide)
Admin or Product Manager access in Kaptio

Part 1: The Package Record

Creating a Package

Navigate to Packages in Kaptio and click New. Salesforce will first ask you to choose a record type:

Package — a top-level, sellable product (the trip your customer books)
Bundle — a reusable building block that groups services together (e.g., “3 Nights in Rome” with a hotel + breakfast + city tour), which gets nested inside a Package as a component option

Choose Bundle when creating a shared segment that will be re-used across multiple packages.

After selecting the record type, fill in the required fields:

Field	API Name	Description	Behavior
Name	`Name`	The display name shown in search results and documents	Free text; use a clear, customer-facing title
Departure Type	`DepartureType__c`	Anyday, Seasonal, or Fixed	Choose carefully — changing after save may affect departures, seasons, and components already configured against the package
Duration	`Length__c`	Total trip length in nights	Determines the date span for components
Booking Wizard Unit Number Selection	`PhysicalInventorySelection__c`	Controls whether cabin/room number selection appears in the Booking Wizard	Picklist — see guidance below

Booking Wizard Unit Number Selection values:

Value	When to use
Mandatory (default)	Cruise, rail, or any package where the customer must select a specific cabin or room number during booking. The Booking Wizard displays a Cabins tab that must be completed before the itinerary can be created.
Not Mandatory/Hidden	Land-only packages or packages where cabin/room selection is not needed. The Cabins tab is hidden in the Booking Wizard. For cruise and rail packages, the system auto-assigns a default cabin behind the scenes.
Component Controlled	Mixed packages (e.g., a land tour with an optional cruise segment) where cabin selection should only apply to specific components rather than the entire package. The need for cabin selection is determined by each component’s type.

Package Settings

After saving the package record, configure these additional settings:

Field	API Name	Description	Behavior
Package Code	`PackageCode__c`	Brochure or internal identifier	Used as a prefix for reservation numbers via Tour Code
Active	`IsActive__c`	Controls whether the package appears in search	Leave unchecked until setup is complete
Visibility Setting	`VisibilitySetting__c`	Who can see the package: Visible for All (default) or Restricted	When Restricted, an Access Rule must be assigned
Access Rule	`AccessRule__c`	Controls which channels and accounts can access the package	Only applies when Visibility is Restricted; overrides service-level access rules
Categories	`Categories__c`	Multiselect picklist for filtering and grouping packages	Values are configured in metadata (e.g., Family Package, Adventure Package)
Start Location	`PackageStartLocation__c`	Lookup to Location; used in Package Search
End Location	`PackageEndLocation__c`	Lookup to Location; used in Package Search
Supplier	`Supplier__c`	Primary supplier account for the package	Used for single-supplier prepackaged products
Unpriced	`Unpriced__c`	Shows “Unpriced” in search instead of a price	Use when prices are not yet configured or are available on request

Pricing Setup Fields

Lightning Costings note: Lightning costings only supports Dynamic for both Cost Setup and Selling Price Setup. Fixed cost and fixed sell price modes are legacy (classic costings only) and are not supported in lightning costings. Some fields in the table below only apply to classic costings and are marked accordingly.

These fields control how sell prices are calculated for the package:

Field	API Name	Description	Behavior
Selling Price Setup	`SellingPriceSetupChoice__c`	How sell prices are derived	Dynamic is the supported mode — sell prices are calculated from cost + markup/margin rules
Cost Setup	`NetPriceSetupChoice__c`	How cost prices are derived	Dynamic is the supported mode — cost prices are calculated from service pricing or from a 3rd party source
Sell Price Rounding	`SellPriceRounding__c`	Rounding rule for calculated sell prices	Overrides the channel-level rounding setting for required components
Primary Pricing Component (Classic only)	`PrimaryPricingComponent__c`	Which component drives the primary price split	Only relevant for fixed cost or sell price setups (classic costings). Not used in lightning costings where Dynamic is the only supported mode
Profitability Group	`ProfitabilityGroup__c`	Links to a Profitability Book for margin targets	See Cost & Pricing Architecture
Commission Group	`CommissionGroup__c`	Reseller commission grouping	Can be overridden at the component or price category level
Discount Group	`DiscountGroup__c`	Discount rule grouping	Can be overridden at the component or add-on level

Service Level Mode

The Service Level Mode (ServiceLevelMode__c) field controls whether the package supports tiered pricing:

Mode	Behavior
Standard	Single pricing tier — no service level selection during booking
Service Levels	Multiple tiers (e.g., Standard, Superior, Luxury) — guest selects a tier
Package Levels	Cabin-level selection — used for cruise-style products with cabin categories

See Service Level Configuration for detailed setup, or Package Level Configuration for cabin-category pricing on cruise and rail products.

Part 2: Components

What Components Are

Components are the building blocks of a package. Each component represents a segment of the trip — a hotel stay, an activity, a transfer, a rail segment. The package is a container; the components hold the product and pricing.

Component Types

Type	Purpose	Example
Bundle	Groups multiple services into a single destination segment	”City A — 3 Night Stay” (hotel + breakfast + city tour)
Component	A single service with structured pricing	”Airport Transfer”, “Guided Walking Tour”
Live	Real-time pricing from an external system	”Dynamic Rail Fare” via Kaptio Connect

Creating Components

From the package record, navigate to the Components related list and click New.

Field	API Name	Description	Behavior
Name	`Name`	Descriptive label for the component	Shown in Builder, Costings, and customer documents
Component Type	`ComponentType__c`	Bundle, Component, or Live	Determines the structure and pricing behavior
Sort	`Sort__c`	Display order in the itinerary	Components are rendered in ascending sort order
Start Day	`Start__c`	Day number when this component begins	Mandatory; determines placement within the package duration
End Day	`End__c`	Day number when this component ends	For multi-day components (e.g., accommodation spanning 3 nights)
Is Active	`IsActive__c`	Whether the component is selectable	Inactive components are hidden from booking flows
Is Main Component	`IsMainComponent__c`	Core component for summaries and cancellation rules	Affects which component drives package-level policies
Is Main Tour Component	`IsMainTourComponent__c`	The single primary tour/cruise component	Only one component should have this flag; drives tour-level summaries

Component Behavior Fields

These fields control how the component behaves during booking:

Field	API Name	Behavior
Selection Type	`SelectionType__c`	How the guest interacts with this component during booking — see Selection Type values below
Component Behaviour	`ComponentBehaviourChoice__c`	Single-day vs multi-day behavior
Booking Wizard Tab	`BookingWizardTab__c`	Which tab this component appears on in the Booking Wizard
Day by Day Display	`DayByDayDisplay__c`	How the component appears in day-by-day search results
Inventory Required	`InventoryRequired__c`	Whether this component affects package availability
Available Anyday	`IsAvailableAnyday__c`	For single-day services: allow any day within the package dates
Package Totals	`PackageTotals__c`	Whether this component’s price is included in the package total
Pricing Behaviour	`PricingBehaviorChoice__c`	Controls whether cost and sell prices from the supplier service are applied — see Pricing Behaviour values below
Allocation Behavior	`AllocationBehavior__c`	Controls which nights of an accommodation stay consume allotment — see Allocation Behavior values below
Included	`IsIncluded__c`	Whether this component is included when booking — for add-on components: controls whether the component is included by default or opt-in
Is Mandatory Optional	`IsMandatoryOptional__c`	Optional component that still requires a selection in Booking Wizard

Selection Type Values

The Selection Type determines whether a component is included in the itinerary by default and what happens if the guest removes it:

Value	Behavior
Pre-Selected Refundable	The component is included in the itinerary by default. The guest can remove it during booking, and the cost is removed from the package total — the guest is not charged for it. Use this for standard included components where the guest has the option to opt out.
Optional	The component is not included in the itinerary by default. The guest can add it during booking if they want it. Use this for extras, upgrades, and add-on experiences that the guest opts into.
Pre-Selected Non-Refundable	The component is included in the itinerary by default. If the guest removes it during booking, the cost remains on the package total — the guest still pays for it even though the service is removed. Use this for components where the operator has committed cost that cannot be waived (e.g., a group transfer or charter segment).

Pricing Behaviour Values

The Pricing Behaviour field controls whether cost and sell prices from the associated supplier service are applied to the itinerary. Set this according to the pricing you want for the component:

Value	Effect
Standard	Both cost and selling price from the associated supplier service will be used. This is the default for most components.
Free Component	There is no cost or sell price added to the Itinerary, even if the supplier service has a valid cost or sell price for the booking date. Use this for complimentary inclusions where you do not want any pricing to appear.
No Cost Rate	The cost rate from the supplier service will not be added to the Itinerary, but the sales rate will be. Use this when you want to charge the customer but treat the component as zero-cost internally (e.g., bundled services where the cost is already accounted for elsewhere).
No Sales Rate	The sell rate from the supplier service will not be added to the Itinerary, but the cost rate will be. Use this when you need to track the supplier cost but do not want the component to contribute to the customer-facing price (e.g., an included transfer where the cost is absorbed into the package margin).

Allocation Behavior Values

The Allocation Behavior field controls which nights of an accommodation stay consume allotment. This is a specialist field that only appears when the Allotment Categories setting is enabled in your org — most users will not see it. When visible, it is typically set automatically based on the component’s record type.

Value	Behavior
Standard	All nights of the stay consume allotment from the standard allotment category. This is the default.
PreNight	The stay consumes allotment from the pre-night allotment category. Used for pre-tour accommodation components (e.g., an extra night before the main tour starts).
PostNight	The stay consumes allotment from the post-night allotment category. Used for post-tour accommodation components (e.g., an extra night after the main tour ends).

Note: If you do not use Allotment Categories, this field can be ignored — allotment consumption defaults to Standard behavior automatically.

Pre/Post Stay Components

For accommodation components that support flexible check-in/check-out:

Field	API Name	Behavior
Min Number of Nights	`MinNumberOfNights__c`	Minimum nights the guest can select
Max Number of Nights	`MaxNumberOfNights__c`	Maximum nights the guest can select
Create Itinerary Item Per Night Per Room	`CreateItineraryItemPerNightPerRoom__c`	Creates separate line items for multi-night pre/post stays

See Pre/Post Stay Configuration for the full setup.

Part 3: Component Options (Assigning Services)

What Component Options Are

Component Options link supplier services to components. Each option represents one possible service that can fulfil the component. A hotel component might have three options: Hotel A, Hotel B, Hotel C — the guest (or the default) selects one.

Creating Component Options

For each component, click New Component Option. The creation flow starts by selecting the Supplier (Account), which filters the available services — then select the Service from that supplier. After the service is linked, configure the remaining fields:

Field	API Name	Description	Behavior
Service	`Item__c`	The supplier service	Lookup to `Item__c` (Service) — selected after choosing the Supplier
Price Category	`PriceCategory__c`	Which price category to use	Links to the service’s pricing tier
Sort	`Sort__c`	Display order of options within the component	Options shown in ascending sort order
Service Sort	`ServiceSort__c`	Controls which service is auto-selected when other options are filtered out (e.g., sold out or unavailable)	The defaulting priority is: (1) the option marked as Default is chosen first; (2) otherwise, the lowest Service Sort value wins; (3) if Service Sort values are equal or unset, the Sorting Scheme is used (if configured); (4) without any of the above, the order is undefined. For example, if a hotel component has three options with Service Sort values 1, 2, and 3, and a filtering scheme removes sold-out services, the system selects the lowest available option automatically. Sorting is from lowest to highest value (1 = first).
Default	`IsDefault__c`	Marks this as the default option	When a package is added to a quote, the default option is pre-selected. See Advanced Defaulting for more complex defaulting rules.
Mandatory	`IsMandatory__c`	Whether the add-on is automatically included	Only applicable to Add-ons — when checked, the add-on is automatically added to the service during booking. If unchecked, the add-on will not be added. Users do not have the opportunity to add mandatory add-ons manually in Package Search; the system handles them automatically.
Unpriced	`Unpriced__c`	Shows “Unpriced” in Booking Wizard	For options where pricing is handled separately

Additional Option Fields

Field	API Name	Behavior
Add-on	`Addon__c`	Links to an add-on record
Board Basis	`BoardBasis__c`	Meal plan assignment
Service Level	`ServiceLevel__c`	Which service level tier this option belongs to
Pricelist	`Pricelist__c`	Option-specific pricing for dynamic packages
Pre-Selected in Costings	`IsPreSelectedInCostings__c`	Auto-selects this optional component option as the default when a Package is added to an Itinerary via Costings (not used in Package Search)

Rail Component Fields

The following fields apply to Rail components only:

Field	API Name	Behavior
Arrival Location	`ArrivalLocation__c`	Arrival point for the rail segment
Departure Location	`DepartureLocation__c`	Departure point for the rail segment
Fare Class	`FareClass__c`	Rail fare class (e.g., Standard, Premium, Bedroom)
Available Times	`AvailableTimes__c`	Default departure/arrival times for this rail option

Part 4: Sort Order and Display

How Sort Order Works

Two concepts work together here: display order (what sequence things appear in on screen) and auto-selection (which option the system picks when you add the package to a booking). They use different fields and follow different logic.

Display Order

Display order controls the sequence in which components and options appear in the Package Editor, Booking Wizard, Builder, Costings, and customer-facing documents.

Components are ordered by the Sort__c field on Component__c — lowest number first (ascending). A component with Sort 10 appears before Sort 20.
Options within a component are ordered by ComponentOption__c.Sort__c — again lowest first.
In some UI contexts, the option marked as Default (IsDefault__c = true) is promoted to the top of the list regardless of its sort value.

Use increments of 10 (10, 20, 30…) so you can insert new components or options later without renumbering everything.

How the System Picks a Default

When a package is added to a quote, the system needs to auto-select one option per component. It follows this priority, top to bottom — the first rule that produces a match wins:

Default flag — if one option has IsDefault__c checked, it is selected. Done.
Lowest Service Sort — if no Default flag is set, the system picks the option with the lowest ServiceSort__c value (1 beats 2, 2 beats 3, etc.).
Sorting Scheme — if Service Sort values are equal or unset, and the component has a Sorting Scheme configured (via ComponentDefault__c), the scheme’s JSON rules determine the winner.
Undefined — if none of the above apply, the selection order is undefined and you should not rely on which option gets picked.

Worked Example

Imagine a hotel component with three options:

Option	Default?	Service Sort	Status
Hotel A	No	1	Available
Hotel B	No	2	Sold Out
Hotel C	Yes	3	Available

Auto-selection: Hotel C is picked because the Default flag (rule 1) takes priority — even though Hotel A has a lower Service Sort value.
Display order: The options appear in Sort order (determined by each option’s Sort__c field), with Hotel C potentially promoted to the top of the list in some UI contexts because it is the Default.
If Hotel C were sold out: The Default flag no longer applies (the option is unavailable). The system falls to rule 2 and selects Hotel A (Service Sort 1, and it is available). Hotel B (Service Sort 2) is skipped because it is also sold out.

Best practices:

Accommodation bundles anchor the major segments (lowest sort values per city/destination)
Activities and transfers follow their parent bundle in sort order
Live components slot in wherever the transport segment occurs
Keep sort values consistent across similar packages for operational efficiency

Advanced Defaulting

Beyond the simple IsDefault__c flag on component options, Kaptio supports advanced defaulting through the ComponentDefault__c object:

Field	Purpose
Component	Which component this default applies to
Default Service	The service to use as default (lookup to `Item__c`)
Service Level	Scope the default to a specific service level
Context	Parent option when the component is inside a bundle — defaults on the outer package override defaults on a bundle’s inner component
Filtering Scheme	JSON conditions to filter which options are eligible before defaulting
Sorting Scheme	JSON conditions to sort eligible options (e.g., by cost, by availability) before selecting the default

Advanced defaulting is typically used when:

Options should be filtered or sorted by external criteria before defaulting
Bundle-level defaults need to override inner component defaults

Part 5: Filtering Package Search Results

Categories, access rules, and activity-level fields all control how packages appear and can be filtered in Package Search. This section groups them together so you can configure search behavior in one pass.

Access Rules

Access rules control which channels and accounts can see and book a package. They only apply when the package’s Visibility Setting is set to Restricted. For the full standalone reference — including service-level visibility and troubleshooting — see Visibility Settings & Access Rules.

How access rules work:

Create an AccessRule__c record
Assign channels to the rule via ChannelAccessRuleAssignment__c
Optionally assign accounts via AccountAccessRuleAssignment__c
Link the rule to the package via the AccessRule__c field

When a package has a Restricted visibility and an access rule assigned:

Only channels and accounts linked to that access rule can see the package in search
Package-level access rules override any access rules set on individual services within the package

When Visibility Setting is Visible for All, the Access Rule field is ignored — all channels and accounts can see the package.

Activity Level and Pace

Field	API Name	Purpose
Activity Level	`ActivityLevel__c`	Physical demand rating for travellers
Pace	`Pace__c`	Daily schedule tempo
Minimum Age	`MinimumAge__c`	Recommended minimum guest age

These fields are informational — they appear in search results and documents but do not affect pricing or availability.

Part 6: Other Package-Level Settings

Single Supplier Packages

Field	API Name	Purpose
Prepackaged by Single Supplier	`PrepackagedBySingleSupplier__c`	Marks packages where all services come from one supplier

Validation Checklist

Kaptio includes validation rules on Package, Component, and Component Option records that enforce required field combinations at save time. The checklists below serve as a manual QC process to catch configuration issues that validation rules alone do not cover — such as sort order, default selection, and category assignments.

For automated post-build verification, use Costings or Builder to test pricing calculations, and the Package Search API to confirm the package appears correctly with the expected filters and pricing. See Package Search Troubleshooting for post-build verification steps.

Before activating any package, verify:

Package Record

Departure Type is correct (cannot be changed after save)
Duration matches the total trip length in nights
Categories are assigned for search filtering
Visibility Setting and Access Rule are configured
Start and End Locations are set

Components

Sort order produces the correct itinerary sequence
Start Day and End Day are set on each component
At least one component is marked as Main Component (if using Booking Wizard and Cancellation Configurations)
No duplicate or orphaned components exist

Component Options

Every component has at least one option assigned
Default options are marked for components with multiple choices
Service Level assignments are correct (if using tiers)
Price Categories are selected on each option
Sort order of options matches the intended display sequence

Activation

Activate the package and run a test search
Verify the package appears with correct pricing
Confirm component ordering matches expectations
Test with different service levels (if applicable)

Common Issues and Solutions

Issue	Likely Cause	Solution
Package not appearing in search	`Active` is unchecked, or Visibility is Restricted with no matching Access Rule	Check Active flag; verify Access Rule assignments match the search channel
Components in wrong order	Sort values are incorrect or missing	Review `Sort__c` on each component; use increments of 10
Wrong service selected by default	`IsDefault__c` not set, or advanced defaulting overriding	Check `IsDefault__c` on component options; review `ComponentDefault__c` records if using advanced defaulting
Package shows “Unpriced”	`Unpriced__c` is checked on the package or a component option	Uncheck the flag, or verify that pricing is configured
Component not appearing in Booking Wizard	Component is inactive (`IsActive__c = false`) or Booking Wizard Tab is not set	Activate the component and verify the tab assignment
Access Rule not working	Access Rules are only available when Visibility is set to Restricted — the rule likely has an incorrect Channel or Account configured	Check the Access Rule to ensure the correct Channel or Account is assigned
Categories not filtering correctly	Using deprecated `Category__c` field instead of `Categories__c`	Switch to the multiselect `Categories__c` field

Object	API Name	Purpose
Package	`KaptioTravel__Package__c`	Top-level product container
Component	`KaptioTravel__Component__c`	Segment within a package (Bundle, Component, Live)
Component Option	`KaptioTravel__ComponentOption__c`	Links a supplier service to a component
Component Default	`KaptioTravel__ComponentDefault__c`	Advanced defaulting rules with filtering and sorting schemes
Access Rule	`KaptioTravel__AccessRule__c`	Controls channel and account access to packages
Channel Access Rule Assignment	`KaptioTravel__ChannelAccessRuleAssignment__c`	Links a channel to an access rule
Account Access Rule Assignment	`KaptioTravel__AccountAccessRuleAssignment__c`	Links an account to an access rule
Service	`KaptioTravel__Item__c`	Supplier service offering
Service Level	`KaptioTravel__ServiceLevel__c`	Pricing tier (Standard, Superior, Luxury)