Feature Spec: Ancillary Catalog & Extras (Backoffice)

Goal: Define how operators create and manage bookable extras (insurance, room upgrades, excursions, meals) on tour templates, how these flow to the booking widget, and how they appear in the workspace.

---

Domain Concepts

Centralized, Overridable Design

Operators define extras once at the operator level (the "Catalog"), then attach them to templates. Per-template and per-departure overrides follow the same cascade pattern as boarding points and deposit config.

Convention over Configuration

The 6 behavioral types (INSURANCE, UPGRADE, EXTRA_LUGGAGE, EXCURSION, MEAL, OTHER) are system-defined conventions. Operators pick a type and provide a label — they never define behavioral categories. This allows the system to determine refund rules, reporting, and invoice line grouping automatically.

---

Data Model

Tier 1: Operator-Level Catalog

A global library of extras that the operator maintains. Reusable across all templates.

backoffice.ancillary_catalog_items

Column	Type	Constraints	Description
id	UUID	Primary Key	Unique catalog item
tenant_id	UUID	FK (operators.id), Not Null	Owning tenant
type	VARCHAR	Not Null	Behavioral category: INSURANCE, UPGRADE, EXTRA_LUGGAGE, EXCURSION, MEAL, OTHER.
label	VARCHAR	Not Null	Operator-defined display name shown to passengers
description	TEXT	Nullable	Optional longer description for the booking widget product page
cover_image_key	VARCHAR	Nullable	Optional image key for displaying the item in the booking widget.
default_price	DECIMAL	Not Null	Default unit price in the operator's currency
currency	VARCHAR	Not Null, Default: EUR	ISO 4217
is_per_passenger	BOOLEAN	Not Null, Default: true	true: price applies per passenger. false: price applies per booking.
max_quantity	INT	Nullable	Maximum units per booking. Null = unlimited.
tax_strategy_override	VARCHAR	Nullable	STANDARD_VAT or MARGIN_SCHEME_25. Null = inherit from the parent tour's tax strategy.
status	VARCHAR	Not Null, Default: ACTIVE	ACTIVE or ARCHIVED. Archived items remain on existing bookings but do not appear in new checkouts.
sort_order	INT	Not Null, Default: 0	Display order in the booking widget and template configuration

NOTE

Unique constraint: (tenant_id, label) — prevents duplicate names within a tenant.

Tier 2: Template-Level Assignment

Which catalog items are offered on which tour template, with optional price overrides. (Note: Bundling of ancillaries is explicitly deferred to [future]).

backoffice.template_ancillary_assignments

Column	Type	Constraints	Description
id	UUID	Primary Key	Unique assignment
tenant_id	UUID	FK (operators.id), Not Null	Owning tenant
tour_template_id	UUID	FK (tour_templates.id), Not Null	Target template
ancillary_catalog_item_id	UUID	FK (ancillary_catalog_items.id), Not Null	Catalog item being assigned
price_override	DECIMAL	Nullable	Per-template price override. Null = use default_price from catalog.
included_by_default	BOOLEAN	Not Null, Default: false	true: auto-added to every booking (e.g., travel insurance on premium tours). Passenger can opt out.
enabled	BOOLEAN	Not Null, Default: true	Quick toggle to disable an extra for this template without removing the assignment.

Tier 3: Departure-Level Override (Inherited)

Departures inherit their template's ancillary assignments.

• Default behavior: A departure inherits all assignments from its template. No separate table needed at [v0.1].
• [v0.2]: Add a departure_ancillary_overrides table for per-departure price changes or disabling specific items.

Resolution Cascade

Effective Price = departure_override ?? template_override ?? catalog_default_price
Effective Enabled = departure_enabled ?? template_enabled ?? true (if assigned)

---

Commerce Projection

When a TourDeparture publishes, the payload includes the resolved ancillary catalog for that departure:

interface TripPublishedAncillary {
  catalog_item_id: string;
  type: AncillaryType;
  label: string;
  description: string | null;
  cover_image_key: string | null;
  price: number;
  currency: string;
  is_per_passenger: boolean;
  max_quantity: number | null;
  included_by_default: boolean;
  sort_order: number;
}

Commerce stores this as a denormalized JSONB array on tour_offerings.available_ancillaries.

IMPORTANT

New column on commerce.ancillaries: Add catalog_item_id UUID (nullable, soft FK to backoffice.ancillary_catalog_items). Null for manually added ancillaries. Enables Backoffice → Commerce traceability.

---

Workspace UX

Tour Template Detail — Tab 5: Settings

Ancillaries live in the Settings tab under an "Extras & Add-ons" section.

Layout: A card-list showing all ancillary catalog items assigned to this template. Actions:

• "Add Extra" → Picker showing all ACTIVE catalog items not yet assigned to this template. Multi-select enabled.
• "Edit Price" → Inline edit the price_override.
• "Manage Catalog" → Navigates to /settings/catalog.
• Remove (trash icon) → Removes the assignment.

Global Ancillary Catalog Management

Path: /settings/catalogLayout: Table of all ancillary_catalog_items for the tenant.

Smart Defaults (Concierge Onboarding): The tenant provisioning flow seeds 3 starter items (e.g., Reiserücktrittsversicherung, Einzelzimmerzuschlag, Zusatzgepäck). Operators customize labels and prices immediately — they never face an empty catalog.

---

Commerce UX: Passenger Side (Booking Widget)

During checkout, after the passenger selects their boarding point and ticket type:

Step: "Extras & Add-ons"

• Cards for each available ancillary, sorted by sort_order.
• Items with included_by_default = true appear pre-selected with an "Included" badge. The passenger can remove them.
• Each card shows: label, cover image (if present), price, description.
• Toggle to add/remove. Quantity selector if max_quantity > 1.
• Note: Availability of specific ancillaries based on the chosen boarding point is explicitly deferred.

---

V0.1 Pricing Tab Clarification

The V0.1 pricing model uses Centralized Pricing Categories + Base Price + Overrides.

Operator-Level: Pricing Categories

Path: /settings/pricing Operators define reusable pricing categories (e.g., ADULT, CHILD, INFANT) with discount_type and discount_value. Exactly one category is marked as base (is_base = true).

Template-Level: Base Price + Category Overrides

1. Base Price — A single number field: "Adult price per person".
2. Category List — Shows all operator-level pricing categories with the computed price based on the category discount.
3. Per-template overrides — The operator can override the discount for a specific category on this template.

(No CostingSheet, no margin calculator, no multi-channel pricing at V0.1).

---

Phasing

Feature	Horizon
Operator-level ancillary catalog (CRUD)	[v0.1]
Template → ancillary assignment with price overrides	[v0.1]
Commerce projection via TripPublished	[v0.1]
Booking widget: extras selection step	[v0.1]
Concierge onboarding seeds (3 starter items)	[v0.1]
Operator-level pricing categories (CRUD)	[v0.1]
Template base price + category overrides	[v0.1]
Ancillary cover image support	[v0.1]
Departure-level ancillary overrides	[v0.2]
Per-departure pricing overrides	[v0.2]
B2B reseller pricing catalogs	[v0.2]
Ancillary analytics	[v0.2]
Filter ancillaries by Boarding Point	[future]
Ancillary Bundling	[future]