PragmaticTours User Manual

Welcome to PragmaticTours! This guide explains how to use the platform in your daily work. It is written for tour agency staff — dispatchers, coordinators, guides, and administrators.

Getting Started
Your Dashboard
Calendar View
Managing Tours
Bookings & Customers
Quotes, Proposals & Pre-Invoices
Product Catalog
Fleet Management
Locations & Operational Zones
Team Management
Dispatch & Assignments
Auto-Assignment & Optimization
Notification Engine & Multi-Channel Communications
Passenger Manifests
Equipment & Inventory
Financial Reports
Payable Report
User Settings
Account Settings
API Reference (v1)

1. Getting Started

Logging In

Open your browser and go to your agency's address (e.g., https://youragency.pragmatictours.com). You can log in with:

Email and password — the account your admin created for you.
Google or Microsoft account — if your agency has turned on this option.

First Time

If you received an invitation by email, click the link in the email. It will take you to a page where you can set up your password. After that, you will be taken to your agency's workspace.

Once logged in, you will see a sidebar on the left with these sections:

Menu	Who Can See It	What You Can Do
Dispatch	Everyone	See today's tours and assign staff/vehicles
Calendar	Everyone	View the monthly schedule
Bookings	Admins, Dispatchers	Manage reservations and guests
Quotes & Proposals	Admins, Dispatchers	Build multi-day proposals, pre-invoices, and convert quotes to tours
Customers	Admins, Dispatchers	Manage customer directory and B2B partner agencies
Manifests	Admins, Dispatchers	Upload and process passenger lists
Inventory	Admins, Dispatchers	Manage equipment
Catalog	Admins only	Create tour templates
Fleet	Admins only	Add and manage vehicles
Locations & Zones	Admins only	Create and manage ports, piers, and service areas
Team & Invites	Admins only	Invite and manage staff
Reports	Admins only	View daily revenue, costs, and profit
Payable Report	Admins only	View freelance and vehicle costs
API Keys	Admins only	Generate and revoke API keys
Settings	Everyone	Access account and profile settings

Top Bar

At the top of the page you will find:

Current date — displayed on the left.
Notification bell — (admins and dispatchers only) shows a red badge with your unread count. Click to open a dropdown with recent notifications (new assignments, acceptances, cancellations, reschedules). Click "View all notifications" to see the full list. Notifications arrive in real time — no page refresh needed.
User dropdown — your initials, name, and role on the right. Click to quickly access Profile, Communication Preferences (only when Telegram or WhatsApp channels are enabled), Change Password, Availability Settings, or Sign Out. If you belong to multiple agencies, you can switch accounts or create a new agency here.

2. Your Dashboard

The Dispatch page is your main workspace. It shows you everything happening on a selected day.

Choose a Date

At the top of the page you will see: - A date picker — click to select any date. - Previous / Next day arrows — move one day at a time. - Today button — jumps back to the current date.

What You See

Each tour on that day appears as a card. Every card shows:

Tour name — e.g., "Snorkeling Adventure".
Status — Scheduled, In Progress, Completed, or Cancelled.
Passenger count — how many people are on this tour.
Capacity — seats filled vs total assigned.
Assigned staff — guides, drivers, and captains already assigned.
Assigned vehicles — buses, vans, or boats already assigned.
Missing resources — roles or vehicles that still need to be filled.
Cancel reason dialog — clicking Cancel opens a modal where you enter a reason for the cancellation.

Multi-Day Tours

When a tour was created from a multi-day template, it appears as a single card with a Multi-Day (N days) badge. The card shows:

Parent tour header — the package name and date range (e.g., "Jun 10 – Jun 13").
Day N badge — indicates which day of the multi-day tour is currently displayed.
Child tour name — the specific day plan name, shown below the pickup time.
Child tour data — pickup time, address, assignments, and manifest for that specific day, not the whole package.
Cancel — cancels the entire multi-day tour and all its child tours.
Cancel Day — cancels only the individual day (child tour) shown on the card, without affecting the rest of the package.
Reschedule (all days) — shifts all child tour dates by the same offset.

Fleet Status

On the right side of the dashboard you will see the Fleet Status panel. It shows every active vehicle in your fleet (excluding disabled vehicles) and its status for the selected day:

Status	Meaning
Available (green)	Vehicle is free and ready for assignment.
In Maintenance (red)	Vehicle has a scheduled maintenance block. It will not be suggested by the optimizer.
Unavailable (red)	Vehicle is already assigned to another tour on this day (overlapping time).

3. Calendar View

Click Calendar in the sidebar to see a monthly view.

Each day shows a count of how many tours are scheduled.
Multi-day tours appear on every day they span, not just their start date.
Click any day to see a detailed list of all tours on that date. For multi-day tours, the day detail shows the specific child tour data for that day, including the child tour name below the pickup time.
Use the arrows or the "Today" button to navigate.
The calendar respects your role: guides only see the tours they are assigned to.

4. Managing Tours

Creating a New Tour

The tour creation form adapts based on the template you select. Templates can be single-day or multi-day (see the Product Catalog section).

Single-Day Tour

Go to the Dispatch page for the desired date.
Click "New Tour".
Select a single-day template from the catalog.
Fill in:
Date — defaults to the current day.
Passenger Count — how many people will join.
Pickup Time — required. End Time is auto-calculated from the template duration; you can adjust it later when editing.
Pickup Address — required.
Drop-off Address — optional.
Transit Duration — how long it takes to get there.
Status — default is Scheduled; you can also start the tour immediately.
Staff Compensation — choose between Gig Rate (flat fee per tour) or Hourly Rate. Can be overridden per assignment.
Price per Pax — auto-filled from the template, can be overridden.
Click Save.

Multi-Day Tour

Go to the Dispatch page for the desired start date.
Click "New Tour".
Select a multi-day template (identified with a "Multi-Day" badge in the dropdown).
The form automatically switches to multi-day mode:
Start Date — the first day of the tour (defaults to the selected date).
End Date — auto-calculated from the start date + number of day plans; you can still override it.
Single-day fields (pickup time, pickup address, etc.) are hidden — each day plan on the template provides its own values.
A banner shows how many day plans the template includes.
Fill in Passenger Count, Status, and Staff Compensation — these are shared across all days. The price is auto-calculated from the sum of each day plan's price.
Click Save.

Behind the scenes, the system creates: - A parent tour (multi-day category) with the date range. - One child tour per day plan, each with its own date, pickup time, pickup address, and price per passenger — taken from the single-day template assigned to each plan.

Child tours inherit the passenger count from the parent. Each child can be managed individually from the dashboard or calendar — assign staff, upload manifests, or cancel a single day without affecting the rest of the package.

Form Validation

Before the form is submitted, the system checks that all required fields are filled in. If any required field is empty, the form will show an alert listing the missing fields and highlight them in red. The form will not submit until all required fields are filled.

Required fields include: - Template — must be selected. - Date (single-day) or Start/End Date (multi-day) — must be set. - Passenger Count — must be greater than zero. - Pickup Time and Pickup Address (single-day) — required. - Transit Duration (single-day) — required.

Tour Statuses

Scheduled — the tour is planned and ready for assignments.
In Progress — the tour has started.
Completed — the tour is finished.
Cancelled — the tour will not run. When a tour is cancelled, the card only shows the tour name, status, and cancellation reason (if one was entered) or a "Rescheduled" note. The Required Resources, Equipment Checklist, and Manifest & Assignments sections are hidden.

Editing a Tour

Click on a tour card, then select Edit. You can change any of the details. Once a tour has started, you cannot edit or remove assignments anymore.

Uploading a Manifest to a Tour

From the tour page, you can upload a CSV passenger manifest directly. See the Passenger Manifests section for details.

Cancelling a Tour

Only admins and dispatchers can cancel a tour. A tour must be in Scheduled status to be cancelled.

Open the tour card on the dashboard.
Click Cancel next to the Edit button.
A dialog appears asking for a reason for cancellation. Enter the reason and click Confirm Cancel.

For multi-day tours: - Cancel (parent) — cancels the entire multi-day tour and all its child tours. - Cancel Day — cancels only the individual day (child tour) shown on the card, leaving the rest of the package intact.

When a tour is cancelled: - All pending and confirmed assignments are set to Cancelled. - All equipment check-outs are released. - A cancellation notification email is sent to every confirmed guide and driver. - The tour's status changes to Cancelled and it is moved to the past.

The cancellation reason, who cancelled it, and when are recorded for audit purposes. Once cancelled, the tour card collapses to show only the name, status, and reason — all operational sections (resources, assignments, manifest) are hidden.

Rescheduling a Tour

Rescheduling moves a tour to a new date while preserving its passenger manifest and trying to keep the same staff and vehicles.

Only admins and dispatchers can reschedule. A tour must be in Scheduled status to be rescheduled.

Open the tour card on the dashboard.
Pick the new date using the date picker next to Reschedule.
Click Reschedule.

For multi-day tours: - The button reads "Reschedule (all days)". - All child tour dates are shifted by the same number of days as the parent's start date. - Individual child tours cannot be rescheduled separately.

Behind the scenes: - A new tour is created on the new date with the same settings (pax count, pickup times, addresses). - The passenger manifest rows are transferred to the new tour. - Each confirmed staff member and vehicle is carried over as a draft assignment on the new tour, provided they are available. If a resource is unavailable on the new date, the assignment is silently skipped so the auto-optimizer can fill the gap. - Equipment check-outs are released from the old tour and re-created on the new one. - The original tour is cancelled with an auto-generated note (e.g. "Rescheduled to July 15, 2026"). - A reschedule notification email is sent to every confirmed staff member. - The auto-assignment orchestrator runs on the new tour to fill any gaps left by unavailable resources.

5. Bookings & Customers

The Bookings section allows tour agencies to manage customer reservations, track passenger numbers, and integrate incoming sales directly with daily tour operations.

Overview

A Booking links a primary Customer (lead traveler) to a Tour Template on a specific date, along with any extra passenger names, age categories, and special requirements (e.g., wheelchair assistance or dietary preferences).

How Bookings Are Created

Bookings can be added to PragmaticTours in two ways:

Manual Web Entry:
Go to Bookings in the left sidebar and click "+ New Booking".
Select or create the primary Customer (name, email, phone, language preference).
Select the Tour Template and the Booking Date.
Set the Status (pending, confirmed, or cancelled) and Source (manual_agent, website_widget, etc.).
Add any additional passenger names and special requirements under Booking Passengers.
Click Save.
API & Website Widget Integration:
External websites, booking widgets, or Online Travel Agencies (OTAs) can post bookings programmatically using the Bookings API (POST /api/v1/bookings).
The API automatically matches or creates the customer profile by email (upsert_by_email!).

[!IMPORTANT] Payment Handling & Gateway Policy: PragmaticTours does NOT process payments directly or include integrated payment gateways. Tour operators collect payments using their preferred payment processor (e.g., Stripe, PayPal, local bank transfer, or physical POS credit card terminal). Once payment is received by the operator, the operator or API integration simply marks the booking status as confirmed.

Integration with Tour Schedule & Dashboard

PragmaticTours provides seamless integration between confirmed customer bookings and daily tour logistics:

Automatic Tour Scheduling: When a booking is marked as confirmed, PragmaticTours checks the dashboard schedule for that date and tour template. If no scheduled tour exists yet for that date, PragmaticTours automatically creates and schedules the tour on the dashboard.
Automatic Manifest Syncing: Confirmed bookings automatically sync the lead customer and all extra passengers into the tour's Passenger Manifest and seating list.
Pending Status: Bookings with status pending do NOT auto-create scheduled tours on the dashboard until their status changes to confirmed.
Cancellation: Marking a booking status as cancelled automatically removes its passengers from the scheduled tour's manifest list and updates the tour passenger count.

Customer Management

The Customers page lists all customer profiles registered in your workspace. Customers are uniquely identified by their email address. When a returning customer makes a new booking, PragmaticTours automatically reuses their existing customer profile while updating contact numbers or language preferences, ensuring duplicate customer records are not created.

How to Add a B2B Agency / Partner Account

To register a new B2B Partner Agency or Reseller: 1. Navigate to Customers in the main sidebar menu (/customers). 2. Click the Add Customer button (/customers/new). 3. Enter the agency name in Full Name, email address, and Phone Number (required field). 4. Select Customer Type: Reseller (Commission Agent). 5. Set the agency's Commission Percentage (%) (e.g. 10.0 or 15.0) and default Pricing Tier (Gross Markup or Net Wholesale Rate). 6. Click Save Customer.

Once created, the agency becomes selectable under the Parent Agency / Partner Account dropdown when creating or editing sub-agents or passengers, and can be viewed anytime under the B2B Agencies & Resellers directory filter tab.

6. Quotes, Proposals & Pre-Invoices

The Quotes & Proposals module (accessible to Administrators and Dispatchers) is PragmaticTours' end-to-end commercial engine. It allows tour operators, incoming agencies (DMCs), and charter companies to build bespoke single-day and multi-day itinerary proposals, calculate unit economics and dynamic profit margins, generate branded client presentations and proforma pre-invoices, and convert approved bookings directly into operational tours on your dispatch calendar.

Industry Foundation: What the Quotes Engine Is Based On

In the tourism and incoming agency industry, tour operators historically create custom quotations through a patchwork of disconnected tools: 1. Complex Excel Spreadsheets (.xlsx): Used by product managers and pricing specialists to calculate vehicle charters, guide per-diems, hotel net rates, museum admissions, and passenger tier tables. 2. Word Documents (.docx): Used by sales agents to draft visual proposals, daily itinerary narratives, inclusions/exclusions, and booking conditions. 3. Proforma Invoice Word Templates (.docx): Used by accounting to issue payment requests with wire transfer instructions and agency commission deductions.

While spreadsheets offer flexibility, they create severe operational friction: - Formula Vulnerability: Accidental edits to spreadsheet cells lead to underpriced quotes and lost profits. - Supplier & Fleet Disconnect: Costing sheets rely on static rates that fall out of sync with actual vehicle fleet availability, seasonal room rates, or updated subcontractor prices. - Double Entry & Human Error: When a customer confirms a Word proposal, staff must manually re-type every day, passenger, and service into operational dispatch boards or calendars.

PragmaticTours eliminates spreadsheets and Word templates by integrating the mathematical costing engine, the client-facing presentation canvas, and the operational dispatch calendar into a single, closed-loop workflow.

flowchart TD
    SPREADSHEET["Historical Excel Costing (.xlsx)\nFixed costs, variable tickets, hotel DBL/SGL,\nleader absorption, volume tiers"] --> ENGINE["PragmaticTours Cost Engine (CalculateTotals)\nAutomated waterfall math & real-time health gauge"]
    WORD_DOC["Historical Word Proposal (.docx)\nNarrative, hero photos, itinerary grid"] --> PROPOSAL["Proposal Web Canvas & Chromium PDF\nTailwind-styled, responsive, instant export"]
    PRE_DOC["Historical Word Pre-Invoice (.docx)\nProforma, bank wire details, B2B commissions"] --> PREINVOICE["Pre-Invoice Web Canvas & PDF\nFormal payment request with agency deductions"]
    ENGINE --> PROPOSAL
    ENGINE --> PREINVOICE
    PROPOSAL --> APPROVE["Client Approves Proposal"]
    PREINVOICE --> APPROVE
    APPROVE --> DISPATCH["1-Click Conversion (ApproveAndSchedule)\nInstant scheduled tours, manifests & vehicle dispatch"]

The Costing Waterfall Mathematical Engine

The costing logic behind PragmaticTours' Quotes::CalculateTotals service mirrors the standard incoming DMC financial model:

$$\text{Total Estimated Cost} = \text{Fixed Costs} + \text{Adult Costs} + \text{Children Extra Bed Costs} + \text{Children Sharing Costs} + \text{Infant Costs} + \text{Total Leader Absorbed Costs}$$

Fixed Group Costs ($\text{Cost}_{\text{fixed}}$): Expenses that do not fluctuate with group size, such as private bus or van charters, boat charters, professional lead guide per-diems, driver meals/lodging, and flat vehicle entrance permits.
Variable per-Passenger Costs ($\text{Cost}_{\text{variable}}$): Expenses incurred per individual traveler, including national park entry tickets, museum passes, restaurant meals, domestic flights, wine tastings, and welcome amenities. Items can be marked as Adult Rate or Child Rate.
Children & Family Costing Engine:
In family travel, children have distinct unit economics compared to adults:
- Children with Extra Bed / Couch (children_with_bed_count): Hotels charge a supplemental rollaway bed or couch fee (child_extra_bed_cost on RoomType).
- Children Sharing Room / Existing Bed (children_sharing_count): Hotels charge zero or a minor utility fee (child_sharing_room_cost on RoomType).
- Infants Under 2 Years (infant_count): Travel free or pay minimal insurance/administration costs (cost_per_infant).
- Children Ages (children_ages): Comma-separated ages recorded for supplier rooming lists, airline tickets, and park entries.
Fixed Cost Absorption Mode (absorb_fixed_costs_in_adults):
- Checked (Recommended - Family Standard): Fixed group vehicle and staff costs are absorbed strictly by the paying adults. Children are only charged their specific hotel bed, child meals, child tickets, and child airfares (+ markup).
- Unchecked (Equal Pax Sharing): Fixed group costs are divided equally across all paying participants (adults + children).
Hotel Accommodation & Room Sharing Basis:
Double Sharing (DBL): For travelers sharing a standard double room, the net lodging cost per adult per night is: $$\text{Lodging DBL Share} = \frac{\text{Room Net Rate}}{2}$$
Single Room Supplement (SGL): For solo travelers requiring private rooms, the single room supplement accounts for the full single room net rate versus the double-sharing baseline: $$\text{SGL Supplement} = (\text{Single Room Rate} - \text{Double Share Rate}) \times (1 + \text{Markup \%})$$
FOC Tour Leader / Group Escort Cost Absorption:
In private group travel, overseas agencies frequently bring a Tour Escort or Group Leader on a complimentary (Free of Charge - FOC) basis (foc_leader_count).
The tour leader can stay at a separate hotel or single room (leader_accommodation_id, leader_room_type_id).
The tour leader's single hotel room, guide meals, domestic flight tickets, and admission fees are absorbed across the paying adult passengers: $$\text{Leader Cost per Paying Adult} = \frac{\text{Total FOC Leader Expenses}}{\text{Effective Adult Count}}$$
Gross Profit Margin & Suggested Selling Prices:
The system computes differentiated net costs and suggested retail prices for:
- Adults (Double Occupancy)
- Children with Extra Bed
- Children Sharing Room
- Infants
You can accept suggested prices with one click or enter manual price overrides per traveler category.
Automatic Volume Discount Matrix (Pax Tiers):
Fixed costs are diluted as group size expands. PragmaticTours automatically computes dynamic pricing tiers (e.g. 6–7 pax, 8–9 pax in a Hiace van; 10–11 pax, 12–16 pax in a Coaster minibus), calculating exact DBL, SGL, Child w/ Bed, and Child Sharing selling prices per person.
B2B Wholesale Agency Commissions:
For travel agency partners and resellers, the system deducts their contracted commission percentage (e.g. 10% or 15%) on the pre-invoice, clearly presenting both the gross retail price and the net amount due to your agency.

The 5-Stage Guided Quote Pipeline

Every quote moves through a structured, visual 5-step lifecycle header on its detail page:

stateDiagram-v2
    [*] --> 1_Setup: Create Quote (/quotes/new)
    1_Setup --> 2_Itinerary: Day-by-Day Activities & Lodging
    2_Itinerary --> 3_Costing: Net Costs & Margin Settings
    3_Costing --> 4_Sent: Send Proposal or Pre-Invoice
    4_Sent --> 5_Approved: Client Approves
    5_Approved --> Dispatched: Convert to Operational Tour
    4_Sent --> Cancelled: Client Declines

Pipeline Step	Internal Status (`status`)	Description & Deliverables
1. Trip Setup	`draft`	Define core logistical parameters: travel dates, duration, passenger counts, FOC leaders, client profile, B2B partner, and currency.
2. Itinerary & Activities	`draft`	Build daily schedules, attach single tour templates from your catalog, select hotels and room types, set meal plans (B/L/D), and configure line items.
3. Calculated & Costed	`completed`	Review the live net cost waterfall, set target markup %, override prices if needed, set deposit requirements, and review the volume discount matrix.
4. Proposal / Pre-Invoice Sent	`sent` / `pre_invoice_sent`	Share the responsive web canvas, export high-resolution PDFs, or email documents directly to the client with attached PDFs.
5. Approved & Scheduled	`approved`	Lock the proposal and trigger 1-click conversion to live operational tours in your dispatch calendar.

Financial Health & Profitability Gauge

On the quote detail page, PragmaticTours displays real-time KPI cards: - Estimated Cost: Total accumulated net cost and cost per paying passenger. - Markup / Margin: Target markup percentage and calculated gross profit in dollars. - Price / Person: Current selling price per traveler in the selected currency. - Total Quoted: Full package value quoted to the client. - Agency Commission: Commission percentage and dollar discount for B2B partner agencies. - Deposit Required: Upfront deposit amount (default 30% or custom percentage) required to confirm. - Profitability Status: - Loss Alert (<10% margin): Warns dispatchers when costs threaten profitability. - Tight Margin (10%–25% margin): Indicates modest profitability requiring careful cost management. - Healthy Margin (≥25% margin): Standard commercial profitability.

Step-by-Step: Creating and Building a Quotation

Step 1: Setting Up Trip Logistics (`/quotes/new`)

Navigate to Quotes & Proposals in the left sidebar menu (/quotes).
Click "+ New Quote".
Fill in the core parameters:
Title: A descriptive name for the trip (e.g. "7-Day Panama Highlights & Rainforest Discovery").
Customer: Select an existing customer or toggle "New Customer" to register their name, email, phone, and preferred language inline.
B2B Agent / Reseller (Optional): If quoting for an intermediary wholesale agency, select the partner account to track commission deductions.
Start Date & Duration (Days): Enter the departure date and number of days. The trip's end date syncs automatically.
Passenger & Family Demographics:
- Adults: Number of adult passengers.
- Children (2–11 yrs): Total children count.
- Children with Extra Bed / Couch: Number of children requiring dedicated extra bed rollaways or couches in hotel rooms.
- Children Sharing Existing Room: Number of children sharing existing bed arrangements at zero or reduced hotel rates.
- Infants (<2 yrs): Infants traveling on lap or baby cot.
- Children Ages: Comma-separated list of child ages (e.g. 10, 5) for airline tickets and hotel rooming rosters.
- FOC Tour Leaders: Number of complimentary group escorts whose single room and expenses will be absorbed by paying travelers.
Currency: Base pricing currency (e.g. USD, EUR, GBP, CAD).
Searchable Day 1 Tour Template: Use the interactive searchable select combobox to quickly type and filter single-day tours from your catalog to initialize Day 1 of the itinerary.
Day 1 Group Hotel & Tour Leader Hotel: Select the group hotel and room type, as well as an optional separate Tour Leader hotel and single room type.
Click Create Quote.

Step 2: Day-by-Day Itinerary Builder

Inside the quote workspace (/quotes/:id), the itinerary is organized into sequential day cards:

1. Day Header and Quick Controls

Each day card shows the day number (e.g., D1, D2), calendar date, day title, meal indicators, and lodging tags: - Meal Plan Badges: Quick toggles indicating B (Breakfast), L (Lunch), and D (Dinner). - Lodging Badges: Displays the assigned traveler hotel and room type, as well as the separate Tour Leader single room accommodation. - Transit Hours: Estimated transport and transfer hours for the day.

2. Auto-Populating Days with Searchable Tour Templates

To save time, use the Searchable Tour Template combobox on any day: - Type keywords (e.g. "Canal", "Airport", or code "EXP-01") to instantly filter matching catalog templates. - PragmaticTours automatically copies the tour's title, narrative description, transport hours, guide assignments, vehicle requirements, entrance tickets, and lunch inclusions directly into the day's line items.

3. Managing Line Items (`QuoteItem`)

Within each day, you can add and customize individual cost items: - Categories: - Transport / Vehicle: Private vans, coaches, or airport transfer shuttles. - Boat / Water Taxi: Speedboats, catamarans, or ferry transfers. - Lead Tour Guide: Primary bilingual or specialized expedition guide. - Assistant Guide / Naturalist: Secondary guide or local community naturalist. - Driver / Chauffeur: Dedicated professional chauffeur per-diem. - Attraction / Entrance Ticket: National park admissions, museum fees, indigenous community fees. - Airplane Ticket / Domestic Flight: Regional scheduled or charter flights. - Meal / Restaurant: Group lunches, welcome dinners, or boxed meals. - Perk / Amenity: Bottled water, snack baskets, branded hats, or safety gear. - Hotel / Lodging Room: Additional room charges or day-use rooms. - Custom Expense & Discretionary: Miscellaneous operational costs. - Cost Types & Rate Categories: - Per Traveler (per_pax): Multiplied by the paying passenger count. - Adult Rate vs. Child Rate (rate_category): Tickets, restaurant meals, and domestic flights can be designated as Adult Rate or Child Rate, ensuring child tickets and kid menus do not inflate adult costs or vice-versa. - Flat Group Cost (per_group_flat): Fixed group fee regardless of passenger count (e.g. $350 coach charter). - Per Unit (per_unit): Fixed item multiplied by an explicit quantity. - Supplier Assignment: Link line items to specific registered suppliers in your directory. - Line Item Toggles: - Include in Proposal (include_in_proposal): Checked by default. When checked, the item appears in the client's proposal narrative under "Includes". Uncheck it for internal operational costs that clients shouldn't see as separate bullet points. - Tour Leader Cost (is_leader_cost): Check this box if the item belongs exclusively to the FOC group leader (e.g. Leader domestic flight ticket or Leader meal). These costs are isolated and absorbed across paying adult passengers.

4. Lodging & Room Selection

At the base of each day, open the Lodging Selector: - Travelers Hotel & Room Type: Select the partner hotel and room type (e.g. Deluxe Ocean View Double). The system applies the double-sharing rate ($ \text{Room Net} / 2 $) to the variable cost per adult, and applies the specific Extra Bed or Sharing Room net rate for children. - Tour Leader Hotel & Room Type: Select the leader's lodging (defaults to the same hotel as the group, with a single room type, or an independent crew hotel). The system adds the full single room net rate to the absorbed leader cost pool.

5. Adding Subsequent Days

Click "+ Add Next Day to Itinerary" at the bottom of the itinerary to append Day 2, Day 3, etc., with pre-populated dates, titles, and inherited lodging defaults.

Step 3: Commercial Calculation & Margin Setting Hub

At the bottom of the quote detail page, the Commercial Pricing Hub (#commercial-pricing) brings together your unit economics:

Net Cost Breakdown Cards:
Fixed Costs: Aggregated vehicle charters, driver fees, and lead guide per-diems.
Variable Costs / Pax: Total tickets, meals, and per-person activities divided by paying pax.
Accommodations (Hotel): Total traveler lodging cost (rooms + children extra beds / sharing).
FOC Leader Absorption: Sum of leader lodging, leader flights, and leader meals, with the exact dollar amount absorbed per paying adult traveler.
Total Net Cost / Pax: The true breakeven cost per passenger for the complete package.
Setting Commercial Margins & Pricing Categories:
Agency Markup %: Enter your target gross margin percentage (e.g. 28.0%). The system immediately recalculates suggested selling prices.
Adult Quoted Price: Adopt suggested adult pricing or enter custom quoted rate.
Children & Infant Commercial Pricing Card:
- Adults Absorb Fixed Costs Toggle (absorb_fixed_costs_in_adults): When checked, fixed vehicle/guide costs are paid by adults; children are only priced on incremental hotel bed, meal, and ticket costs. When unchecked, fixed costs are shared equally by all participants.
- Child w/ Extra Bed Quoted Price: Specific selling price for children requiring an extra bed or rollaway couch.
- Child Sharing Room Quoted Price: Specific discounted selling price for children sharing existing parent bedding.
- Infant Quoted Price: Nominal rate or zero for infants under 2 years.
Agency Commission %: If booking through a wholesale B2B travel agent, enter their commission percentage (e.g. 12.0%). The pre-invoice will deduct this amount from the total quoted price.
Deposit Required %: Specify the required confirmation deposit (e.g. 30.0%). The system computes the exact deposit amount in your currency.
Volume Discount Pricing Matrix:
Dynamic tiered matrix displaying per-pax Single Room (SGL), Double Sharing (DBL), Child with Bed, and Child Sharing rates across volume brackets (6–7 Pax, 8–9 Pax, 10–11 Pax, 12–16 Pax).
Can be toggled on/off for client-facing proposals via "Include Investment & Rates Table".
- 6–7 PAX (Hiace / Minivan)
- 8–9 PAX (Hiace / Minivan)
- 10–11 PAX (Coaster / Minibus)
- 12–16 PAX (Coaster / Minibus)
Displays per-pax Single Room (SGL) and Double Sharing (DBL) rates, ready to be presented in proposals for group organizers.
Recalculating Totals:
If you modify line items, hotels, or passenger counts, click "Recalculate All Totals" to refresh all math across days, pricing tiers, and document views.

Client Documents: Proposal vs. Pre-Invoice

PragmaticTours provides two distinct document views tailored for different stages of the booking cycle:

Document Attribute	Client Proposal (`/quotes/:id/proposal`)	Commercial Pre-Invoice (`/quotes/:id/pre_invoice`)
Primary Goal	Inspire & Convert: Present a captivating, visual itinerary that wins the client's booking.	Confirm & Collect: Formal commercial payment request for deposit or full settlement.
Target Audience	Travelers, group organizers, corporate event planners, direct retail clients.	Accounting departments, wholesale travel agencies, corporate billing desks.
Visual Tone	Scenic marketing header, typography-rich narrative, meal grids, activity highlights.	Clean, structured proforma invoice, billing references, tax credentials, bold payment totals.
Pricing Display	Quoted package price, per-person rates, single supplements, volume tier matrix.	Gross package price, B2B agency commission deduction line, bold net amount due, deposit required.
Banking & Terms	Highlights deposit percentage and cancellation policies.	Comprehensive wire transfer instructions (SWIFT/IBAN), credit card surcharge notice, payment deadlines.

Client Delivery Methods

Interactive Responsive Web Canvas:
Open "Preview Proposal" or "Preview Pre-Invoice" to view the live client canvas.
Fully responsive on mobile smartphones, tablets, and desktop displays.
Prospective clients can browse day-by-day narratives, review meal inclusions, and download their PDF copy at any time.
Pixel-Perfect Headless Chromium PDF Export:
Click "Download PDF" or "Print / PDF" to trigger server-side rendering via headless Chromium (Quotes::GeneratePdf).
Produces crisp, vector-rendered Letter-sized PDFs with high-resolution headers, exact print margins, and zero awkward page cuts.
Direct Email Delivery (QuoteMailer):
Click "Email PDF to Client" to send the proposal or pre-invoice directly to the customer's registered email address.
The email is dispatched in the customer's language preference (EN, ES, FR, NL, or PT), includes the generated PDF as an attachment, and routes replies directly to the sales specialist's email address.
Duplicating Quotes (/quotes/:id/duplicate):
Need to quote a similar itinerary for another client or alternative dates? Click "Duplicate" on the quote toolbar. PragmaticTours creates a new draft quote with identical days, line items, and hotels, ready for immediate customization.

The Operations Bridge: Converting Quotes into Dispatched Tours

The decisive advantage of PragmaticTours over Excel and Word is the one-click operational bridge (Quotes::ApproveAndSchedule):

Once the customer agrees to terms and sends their deposit, change the quote status to approved or click "Approve & Dispatch".
PragmaticTours automatically schedules the operational tour:
A parent multi-day tour package is created spanning the full date range.
Individual child tour records are generated for each itinerary day on your Dispatch Calendar.
Daily start dates, pickup/dropoff accommodations (pickup_accommodation_id, dropoff_accommodation_id) and physical addresses from the hotel catalog, transport transit hours, passenger counts, and customer booking profiles are migrated automatically.
Lead TourPassenger manifests are attached to parent and child tours with full party notes (e.g. 2 Adults, 2 Children (1 w/ Bed, 1 Sharing, Ages: 10, 5), 1 Infant).
Operational ServiceVouchers are generated for third-party suppliers (coach charter, tour guides, restaurant lunches, entrance tickets, domestic airlines).
The tours immediately appear on your Dispatch Dashboard, where dispatchers can run the Auto-Assignment Optimizer to assign vehicles and staff, or manage passenger manifests!

Downstream Financial & Operational Reporting

Approved quotes flow directly into PragmaticTours' executive reporting suites:

Tour Profitability Report (/report):
Inspect total realized revenues, cumulative itemized expenses, and gross profit margins across both the parent multi-day tour and individual day tours.
Payable Report by Supplier & Expense Category (/payable_report):
Aggregates external vendor commitments by supplier name and expense category:
- Vehicle / Transport (Coach charter, vans, boats)
- Accommodations (Itemized traveler rooms, child extra beds, child sharing room fees, and leader single rooms)
- Guide / Staff (Tour guide per-diems, assistant guides)
- Attraction / Tickets (Adult and child admissions)
- Meals / Restaurants (Adult and child meal plans)
- Domestic Flights (Scheduled and charter flight tickets)
- Perks / Insurance (Travel insurance, amenities)
Reseller Commission Report (/reseller_commission_report):
Tracks wholesale travel agency bookings, gross quoted trip amounts, agency commission percentages and dollars deducted, and net amounts receivable.

Customizing Proposal & Pre-Invoice Formats for Your Agency

Every tour operator has a unique brand personality—whether you operate luxury private wildlife safaris, high-energy adventure expeditions, VIP corporate transfers, or cultural walking tours. Sending generic, cookie-cutter proposals reduces perceived value. PragmaticTours gives you complete freedom to tailor document formats, styling, and branding so your proposals look stunning, professional, and unique to your agency.

1. Managing Templates in the Proposal Templates Module (`/proposal_templates`)

Admins and dispatchers can manage all document formats under Quotes & Proposals → Manage Formats (/proposal_templates): - Filter by Document Type: Manage Proposal formats, Pre-Invoice formats, and Terms & Conditions annexes. - Filter by Language: Maintain distinct templates for EN, ES, FR, NL, and PT. - Default Format per Market: Mark any template as the Default for its type and language. When generating a proposal in Spanish, PragmaticTours automatically selects your Spanish default template. - One-Click Defaults Generator (Seed Defaults): If your account is newly created, click "Seed Defaults" to generate pre-styled, high-converting starter templates in English and Spanish.

flowchart LR
    TEMPLATES["Proposal Templates (/proposal_templates)\nManage HTML formats by type & language"] --> PROPOSAL_EN["Proposal (EN)\nDefault Luxury Template"]
    TEMPLATES --> PROPOSAL_ES["Propuesta (ES)\nDefault DMC Template"]
    TEMPLATES --> PREINVOICE_EN["Pre-Invoice (EN)\nCorporate Proforma"]
    TEMPLATES --> PREINVOICE_ES["Pre-Factura (ES)\nProforma Comercial"]
    ACCOUNT["Account Branding (/settings/account)\nBanners, Bank Wire Info, Social Links"] --> RENDERER["Quotes::RenderDocument"]
    PROPOSAL_EN --> RENDERER
    PROPOSAL_ES --> RENDERER
    PREINVOICE_EN --> RENDERER
    PREINVOICE_ES --> RENDERER
    QUOTE["Quote Data & Pricing Tiers"] --> RENDERER
    RENDERER --> OUTPUT["Client Web Canvas & Headless PDF"]

2. Styling Proposals with HTML and Tailwind CSS

When editing a template (/proposal_templates/:id/edit), you write standard HTML paired with Tailwind CSS utility classes. This allows full creative freedom:

Typography & Font Styling: Use Tailwind tracking and font weights (e.g. font-black text-3xl tracking-tight, font-serif text-slate-800, or uppercase subtitles text-xs uppercase tracking-widest text-blue-600).
Brand Colors & Badges: Replace generic blues with your agency's color palette (e.g. bg-emerald-900 text-emerald-100 for eco-lodges, bg-amber-900 text-amber-100 for safari operators, or bg-slate-900 text-gold-400 for luxury DMCs).
Hero & Card Containers: Wrap content in clean, rounded cards (bg-white rounded-2xl border border-gray-200 shadow-sm p-6).
Print Optimization & Page Breaks:
Add print:p-0 print:space-y-4 to remove screen padding when printing or generating PDFs.
Use Tailwind's break-inside-avoid on daily itinerary cards and pricing tables so that pages never cut in half across a day's schedule.

3. Complete Dynamic Merge Tags Reference

During rendering (Quotes::RenderDocument), PragmaticTours scans the template and replaces dynamic merge tags with live quote data:

Company & Header Tags

Dynamic Tag	Output Description	Example
`{{company_name}}`	Registered agency business name	"Panama Trails DMC"
`{{agency_phone}}`	Agency operational contact phone	"+507 833-9000"
`{{header_image}}`	Responsive HTML image tag with uploaded banner	`<img src="data:image/png;base64..." class="header-image" />`
`{{agency_header}}`	Complete formatted header banner or text fallback	Header banner block with company name & reference
`{{agency_footer}}`	Agency contact block with phone, email & socials	Footer with vector social icons
`{{social_links}}`	Clickable SVG social network links (WhatsApp, IG, FB)	Formatted SVG icon links
`{{powered_by}}`	Free tier attribution link (omitted on paid plans)	"Power by: https://pragmatictours.com"

Quote Metadata & Client Tags

Dynamic Tag	Output Description	Example
`{{quote_number}}`	System quote reference number	`"QT-2026-0042"`
`{{title}}`	Proposal title	"7-Day Panama Rainforest & San Blas"
`{{issue_date}}`	Date document was created or printed	"October 29, 2026"
`{{payment_due_date}}`	Calculated settlement due date (15 days prior to trip)	"November 15, 2026"
`{{customer_name}}`	Lead traveler full name	"Dr. Victoria Bennett"
`{{customer_email}}`	Client email address	"v.bennett@example.com"
`{{customer_phone}}`	Client phone number	"+1 (415) 555-0192"
`{{agent_name}}`	Responsible sales agent or B2B reseller	"Sarah Jenkins" or "Direct Booking"
`{{start_date}}`	Tour start / arrival date	"November 30, 2026"
`{{end_date}}`	Tour completion / departure date	"December 06, 2026"
`{{duration_days}}`	Total trip duration formatted	"7 Days"
`{{pax_count}}`	Number of paying travelers	`"12"`
`{{foc_leader_count}}`	Number of free-of-charge tour leaders	`"1"`
`{{pax_formatted}}`	Formatted passenger count with leader	`"12+1"`

Financial & Rates Tags

Dynamic Tag	Output Description	Example
`{{currency}}`	Selected currency code	`"USD"`
`{{total_estimated_cost}}`	Total accumulated net operational cost	"$14,280.00 USD"
`{{quoted_price_per_pax}}`	Quoted rate per person (double occupancy)	"$1,750.00 USD"
`{{quoted_price_sgl}}`	Quoted rate per person in single room	"$2,150.00 USD"
`{{quoted_price_dbl}}`	Quoted rate per person sharing double room	"$1,750.00 USD"
`{{total_quoted_price}}`	Total gross package price	"$21,000.00 USD"
`{{deposit_required_amount}}`	Required upfront confirmation deposit	"$6,300.00 USD"
`{{agent_commission_percentage}}`	B2B agency commission percentage	`"10.0%"`
`{{agent_commission_amount}}`	Dollar value of commission discount	"$2,100.00 USD"
`{{net_amount_due}}`	Net amount payable after commission deduction	"$18,900.00 USD"
`{{credit_card_notice}}`	Administrative surcharge notice for credit card payments	"Payments made by Credit Card (Visa/Mastercard) are subject to a 4% administrative fee."
`{{bank_details}}`	Formatted wire transfer bank instructions	Bank name, account number, SWIFT/BIC, IBAN

Dynamic Rich Tables & Narrative Blocks

Dynamic Tag	Generated Rich Component
`{{itinerary_summary_table}}`	Meal Plan & Lodging Overview Table: A responsive grid listing Day number, Breakfast (✓/—), Lunch (✓/—), Dinner (✓/—), itinerary service title, and hotel name.
`{{hotel_descriptions}}` / `{{hotel_details}}`	Hotel Details Cards: Formatted cards rendered once below the Program Overview table listing each distinct hotel's name, physical address, and localized description in the quote's language. If a hotel has no description in the quote's language, it is omitted; if no hotels have descriptions in that language, the entire section is cleanly hidden.
`{{itinerary_detailed_narrative}}`	Daily Service Inclusions Narrative: Day cards with daily titles, descriptive narrative, and a bulleted list of inclusions marked with `included_in_proposal`.
`{{pricing_tiers_table}}`	Volume Discount Pricing Matrix: A formatted table displaying group size tiers (6–7 pax, 8–9 pax, 10–11 pax, 12–16 pax), vehicle tier category, Single room rate (SGL), and Double room sharing rate (DBL).
`{{payment_terms}}`	Formatted payment terms and schedule clauses.
`{{cancellation_policy}}`	Standard sliding-scale cancellation and refund penalty terms.
`{{client_notes}}`	Special dietary, medical, or logistics notes for the client.

4. Agency Account Branding & Legal Setup (`/settings/account`)

In addition to editing HTML templates, configure your global branding assets under Settings → Account Settings → Proposal & Pre-Invoice Branding:

Proposal Header Banner (proposal_header_image):
Upload a high-resolution marketing banner (PNG, JPEG, or WebP up to 5MB).
Recommended dimensions: 1200 × 300 px.
Features your logo overlaid on a scenic, high-impact landscape representative of your destinations.
Pre-Invoice Header Banner (pre_invoice_header_image):
Upload a clean, corporate header banner.
Recommended dimensions: 1200 × 200 px.
Contains your registered corporate logo, legal company name, physical office address, and government tax registration / VAT number.
Banking & Wire Transfer Instructions (bank_details):
Enter your international wire routing details in your account profile:
- Beneficiary Name: Legal business name on bank account.
- Bank Name & Branch Address: Financial institution name and city.
- Account Number / IBAN: Local account number or international IBAN.
- SWIFT / BIC Code: 8- or 11-character bank identifier code.
- Currency: Accepted incoming currencies (USD, EUR, etc.).
Social Network Profiles:
Add your company's WhatsApp Business, Instagram, Facebook, LinkedIn, and Website URLs.
The system automatically embeds vector SVG icons and clickable links in document footers and web canvases.
Subscription Plan Watermarking:
Basecamp Plan (Free): Documents include a discrete "Power by: https://pragmatictours.com" footer note.
Voyage (Pro) & Expedition (Advanced) Plans: 100% White-Label. All documents, emails, and PDFs are completely unbranded with zero system watermarks.

5. Best-Practice Strategies to Make Proposals Irresistible

To maximize quote conversion rates and build trust with travelers and international tour wholesalers:

Lead with Destination Inspiration, Not Just Pricing:
Use the template editor to place a compelling welcome paragraph right after the hero banner: highlight your agency's local expertise, private naturalist guides, and 24/7 on-the-ground support.
Structure Clean Day Narratives:
When configuring itinerary days, break descriptions into clear Morning, Afternoon, and Evening highlights.
Ensure tickets and perks (e.g. private boat captain, rum tasting, indigenous entrance fees) are checked as "Include in Proposal" so clients see the comprehensive value included in the package.
Make Inclusions and Exclusions Explicit:
Use custom cards to separate what is included (private AC transport, all national park fees, daily breakfasts) from what is excluded (international airfare, personal gratuities, optional alcoholic beverages).
Offer Transparent Volume Brackets for Group Organizers:
When quoting for family reunions, birdwatching clubs, or student groups, embed {{pricing_tiers_table}}. This demonstrates how adding more travelers lowers the per-person rate, encouraging clients to expand their group size.
Streamline B2B Re-Invoicing with Clean Pre-Invoices:
When working with overseas travel agencies, send the Pre-Invoice format: it clearly displays their commission discount, states exact wire transfer coordinates, and specifies the deposit due date, making payment approval effortless for their accounting team.

7. Product Catalog

The Products section (admins only) is where you create and manage tour templates. Templates define the product details (duration, pickup, route) and the resource scaling rules that determine what staff and vehicles are needed.

The 4-Step Tour Template Wizard

Creating or editing a tour template uses an interactive 4-step wizard designed for dispatch efficiency and unit-economics precision:

Step 1: Basics & Route (and Photo Gallery)

Type & Category: Select Single-Day Tour or Multi-Day Package.
Fulfillment Type: Choose In-House (operated with internal fleet and guides) or Reseller (External Supplier) for outsourced provider tours.
Location & Operational Zone: Assign the primary location or operating zone (e.g., Cancun, Riviera Maya, Tulum).
Predefined Guides: Preselect preferred guides who should be prioritized for this tour.
Dynamic Location Filtering: Selecting a location instantly filters the guide checklist to only show team members registered for that specific location. If no guides are assigned to that location, a warning banner appears and displays all unrestricted guides (guides with global mobility).
Quick Management from Template Details: Predefined guides can also be added or removed directly from the Tour Template show page with a 1-click dropdown without reopening the wizard.
Timing & Routing: Name, tour code, duration (hours), default pickup time, pickup address, and transit minutes.
Photo Gallery Upload: Upload multiple high-resolution photos (JPEG, PNG, WEBP). The first image is automatically used as the catalog card cover. Existing photos display in an interactive grid with 1-click removal.

Step 2: Resource Scaling Rules (The Math)

Define exactly what staff and vehicles are required based on passenger manifests.
Static Rules: Flat quantity (e.g. Always 1 Lead Guide, regardless of group size).
Dynamic Rules: Ratios scaling with passengers (e.g. 1 guide per 20 passengers, 1 50-pax bus per 50 passengers).
Equipment & Assets: Attach required gear (helmets, kayaks, radios) linked to inventory rules.

Step 3: Pricing, Services & Cost Breakdown

Base Price & Language Rules: Default selling price per passenger ($) and minimum language threshold (Min Pax per Language).
Restaurant & Meal Costs: Toggle Included to track meal stops. Enter costs per passenger for Breakfast, Lunch, and Dinner, and optionally assign a partner Restaurant / Caterer supplier.
Passenger Insurance & Payables: Toggle Included to specify coverage cost per passenger and link a partner Insurance Provider / Broker supplier. This rate feeds directly into automated payable reports.
Fleet Transport Costing: The system calculates a Fleet Suggestion by averaging the daily cost of matching vehicles in your agency's fleet. Click "Use Suggestion" to auto-fill the field, or enter any Flat Transport Rate override.
Tour Perks & Consumables: Allocate refreshments and amenities per passenger (Chilled Water, Local Beer, Soft Drinks, Fresh Fruit, Snacks, Cigarettes, Wet Towels, or custom perks). Specify quantities per pax and custom unit costs.
Categorized Inclusions & Exclusions Checklist: Standardized categorized checklist (Food & Beverage, Transportation, Guides & Staff, Entrance Fees, Equipment, Health & Safety, Other) allowing 1-click inclusion or exclusion marks.

Step 4: Review & Live Profitability Waterfall

Before saving, the wizard presents a complete financial breakdown per passenger: - Itemized Unit Costs: Breakfast + Lunch + Dinner + Insurance + Amenities/Perks + Allocated Transport/Pax + Staff Labor/Pax. - Live Margin Simulation: Test different group size scenarios (e.g. 5, 15, 30, 50 passengers) to evaluate: - Estimated Cost per Pax - Estimated Gross Profit per Pax ($$ \text{Selling Price} - \text{Total Cost} $$) - Profit Margin % with instant health badges: - 🟢 Healthy ($\ge 25\%$) - 🟡 Tight Margin ($0\% - 24\%$) - 🔴 Projected Loss ($< 0\%$)

Perks & Consumables Catalog (`/perks`)

Manage your agency's master amenity rates in one centralized dashboard accessible from the Product Catalog header: - Default Unit Costs: Set standard costs (e.g. $0.50/water, $1.50/beer, $2.00/fruit). When creating tour templates, these rates auto-populate as defaults. - Add Custom Amenities: Create new items with custom names, categories (Beverage, Food, Alcohol, Amenity, Tobacco, Other), and unit types (bottle, can, portion). - Inline Editing: Quickly adjust rates directly in the table with 1-click Save.

Multi-Day Packages

To create a tour spanning multiple days, choose Multi-Day Package in Step 1. The wizard adapts: 1. Day Plans: Add days and select single-day tour templates for each day, with day-specific pickup times or route overrides. 2. Overnight Lodging: Attach partner hotels, room configurations, and meal plans for each night. 3. Automated Pricing: Derived from the aggregated single-day template costs plus overnight lodging net rates.

Each day plan produces one child tour when a multi-day tour is scheduled.

Template List & Maintenance

Search & Filters: Browse templates by name or code with responsive pagination.
Delete vs. Disable: Templates with existing tours or historical records are safely disabled rather than deleted, preserving reporting integrity. Re-enable anytime with the Enable button.

8. Fleet Management

The Fleet section (admins only) is where you manage all your vehicles — buses, vans, boats, and more.

Adding a Vehicle

Click "Add Vehicle" and fill in:

Name — e.g., "Bus 01" or "Panga 3".
Main Category — choose Road (buses, vans) or Marine (boats, pangas).
Sub-Category — e.g., bus, van, panga, catamaran.
Capacity — how many passengers it can carry.
Registration Number — license plate or hull ID.
Required License — what license the driver or captain must have (e.g., "bus" license for a bus).
Ownership — is this vehicle Owned by your agency or Contracted from a third party? This is used in the Payable Report to distinguish between owned vs contracted vehicle costs.
Fleet Structure (fleet_type) — select Single Physical Asset for distinct individual vehicles (e.g., Bus 01) or Contracted Syndicate Pool for vendor pools (e.g., Panama Canal Panga Syndicate).
Min Units & Max Pool Capacity — specify the minimum units needed and maximum pool capacity (e.g., up to 10 boats). Dynamic unit availability (5/10 Available) is tracked automatically across overlapping tours.
Supplier Name & Representative — optional vendor name and representative user account. When assignments are confirmed, WhatsApp reservation requests are sent directly to the representative.
Driver / Captain Provision — specify Agency Staff (if your agency provides drivers/captains) or Supplier Provided (if the vendor/syndicate includes their own operators with the fleet). When set to Supplier Provided, the auto-assignment optimizer automatically skips internal agency staff allocation and avoids spurious missing staff warnings.
Preferred Operator — the default driver (for road vehicles) or captain (for marine vehicles) that should be suggested whenever this vehicle is assigned. Only staff who hold the correct license and role are shown in the list.
Hourly / Daily Cost — for cost tracking.

Fleet Structure & Vendor Syndicates (Pooled Fleets)

When working with third-party vendors or boat syndicates, you can manage multi-unit fleets under a single catalog entry:

Set Fleet Structure to Contracted Syndicate Pool.
Define the Max Pool Capacity (e.g., 10 boats).
Set Driver / Captain Provision to Supplier Provided if the vendor supplies their own captains/drivers.
Select a Supplier Representative to receive automated WhatsApp booking notifications whenever pool units are assigned to tours.

The system automatically manages dynamic availability on the dispatch board (e.g. 7/10 Available) and prevents over-booking across overlapping tour schedules.

Setting a Preferred Operator

When editing a vehicle, you can select a Preferred Operator from a dropdown. This staff member will be the first suggestion when the system or a dispatcher assigns this vehicle to a tour.

For road vehicles, you can only select staff who are certified as drivers and hold the needed license.
For marine vehicles, you can only select staff who are certified as captains and hold the needed license.

If the preferred operator is unavailable (on vacation, already assigned elsewhere), the system will pick another available operator automatically.

Maintenance & Unavailability

To take a vehicle out of service:

Go to the vehicle's Edit page.
Scroll to the Maintenance Schedules section.
Click "Schedule New Maintenance".
Set the start and end date/time, and a reason (e.g., "Oil change").
The vehicle will automatically be marked unavailable during that period.

Vehicles in maintenance will not appear in the Fleet Status as available, and the optimizer will skip them.

Deleting vs Disabling a Vehicle

When you remove a vehicle: - If the vehicle has no historical assignments, it is permanently deleted. - If the vehicle has past assignments or is currently assigned, it is disabled instead of deleted. A "Disabled" badge appears in the fleet list, and the vehicle will no longer appear as available for new tours or in the Fleet Status panel on the dashboard. - You can assign a Primary Home Base / Location to each vehicle, as well as Additional Service Areas / Zones for assets that cover multiple ports (e.g. a boat servicing both Gatun Lake and Chagres River). - The system enforces location constraints: vehicles are only suggested or auto-assigned to tours operating in a location/zone they serve.

Importing Vehicles from a CSV

You can bulk-import vehicles by clicking "Import" and uploading a CSV file. The file must contain at least a name and capacity column. Optional columns include category, registration, costs, and license.

9. Locations & Operational Zones

The Locations & Zones section (admins only) is where you define geographic service hubs, ports, piers, and operational boundaries for tour dispatching.

Managing Locations

Access Locations & Zones from the left sidebar menu to: - Create a Location: Enter a Name (e.g., Gamboa / Gatun Lake), Code / Tag (e.g., GAM-LAK), Description / Coverage Details, and optional Latitude / Longitude coordinates. - Active / Inactive Status: Toggle active status to temporarily suspend dispatch to a port or area without deleting history. - Edit & Delete: Update location boundaries or remove unused locations.

Linking Fleet Assets & Tour Logistics

Tour Location Binding: When creating a tour template or scheduled tour, select its operational Service Location / Zone. Tours automatically copy their location from the template.
Vehicle Location Matching: In Fleet Management, assign a Primary Home Base / Location and select Additional Service Areas / Zones for assets that operate across multiple hubs. Vehicles marked with All Locations (Global Asset) can operate anywhere.
Dispatch Enforcement:
The Auto-Assignment Optimizer automatically filters out vehicles that do not serve the tour's location.
Manual Dispatch: Attempting to manually assign a vehicle to a tour operating outside its service area displays a location mismatch validation alert.

Min / Max Passenger Capacity & Rich Itineraries

Min & Max Pax Bounds: Set the Minimum Pax Threshold (e.g. 5 passengers required to run) and optional Max Pax Capacity Cap (e.g. max 30 pax cap) on Tour Templates and Tours.
Rich Tour Descriptions: Include long-form Overview, Detailed Itinerary, Inclusions, Exclusions, Pickup Instructions, and Special Requirements directly within tour templates and scheduled tours.

10. Team Management

The Team section (admins only) lets you manage your staff.

Roles

Role	Permissions
Admin	Full access — can manage fleet, team, products, and settings
Dispatcher	Can schedule tours, assign staff, process manifests, manage inventory
Guide	Can view assignments and the calendar, but cannot make changes

Inviting a New Team Member

Go to Team and click "Invite Member".
Fill in:
Email address — the invitation will be sent here.
First and Last Name.
WhatsApp Number — optional. Includes an international country flag selector (e.g. 🇵🇦 +507 Panama, 🇺🇸 +1 USA, 🇲🇽 +52 Mexico, 🇨🇷 +506 Costa Rica, 🇨🇴 +57 Colombia, 🇪🇸 +34 Spain, 🇧🇷 +55 Brazil, 🇦🇷 +54 Argentina, 🇨🇱 +56 Chile, 🇵🇪 +51 Peru, 🇬🇧 +44 UK, 🇩🇪 +49 Germany, 🇫🇷 +33 France, 🇳🇱 +31 Netherlands). If the user has already populated their WhatsApp number on their personal profile settings, it will display automatically. Adding or updating it here syncs to their user profile.
Role — admin, dispatcher, or guide.
Employment Type — employee, freelance, or contractor.
Languages — what languages they speak (used for auto-assignment).
Operator Licenses — what vehicles they are licensed to drive or captain.
Staff Roles — what dispatch roles they can fill (lead guide, guide, driver, captain).
Click Send Invitation.

The invitation expires after 7 days. You can cancel a pending invitation at any time.

Bulk Invite

You can upload a CSV file to invite many people at once. The file must contain at least an email and role column. You can also include optional first_name, last_name, whatsapp, employment_type, languages, licenses, and staff_roles columns.

Editing a Team Member's Profile

Click on a member's name or Manage to edit their certifications, employment type, rates, and WhatsApp phone number (with country flag code dropdown). This is important because the auto-assignment system uses this information to match the right person to each tour.

Languages

Set a team member's languages (e.g., English, Spanish, French). The auto-assignment system matches these languages against the passenger manifest languages. For example:

If a tour has passengers who speak English and French, the system will first look for a guide who speaks both languages.
If no bilingual guide is available, it will assign two guides — one for each language.
A staff member with no languages set is considered flexible and can be assigned to any tour.

Operator Licenses

Set what licenses a team member holds (e.g., "bus", "van", "panga"). The system checks these when assigning drivers or captains to specific vehicles.

Staff Roles

Mark what dispatch roles a team member can perform: lead guide, guide, driver, captain. This determines what kind of assignments they can receive.

Driving Hours Compliance

For team members with Driver or Captain roles, you can set daily and weekly driving hour limits. These fields only appear after you check the Driver or Captain box.

Max Hours per Day — the maximum total working hours this person can accumulate in a single day (e.g., 10).
Max Hours per Week — the maximum total working hours for a rolling 7-day week (e.g., 48).

When these limits are set, the auto-assignment system checks the driver's cumulative hours before suggesting them for a tour. If assigning them would exceed the limit, the system skips them and selects the next available operator instead — even if they are the preferred operator for a vehicle.

This ensures compliance with local driving-hour regulations (e.g., EU drivers' hours rules, FMCSA hours of service). Leave both fields blank to disable the check (no limit enforced).

Service Locations

Assign specific locations or operating zones this team member serves (e.g., Cancun, Riviera Maya, Tulum): - Tour Location Filtering: When a tour is assigned to a specific location, the auto-assignment system only considers guides who serve that location. - Global Mobility (Unrestricted): If a team member has no specific service locations selected, they can be assigned to tours in any location.

Setting Unavailability (Time Blocks)

Staff members can block off time when they are not available. Go to Settings > My Availability and add a time block with a reason (vacation, appointment, etc.). The auto-assignment system will skip them during that period.

Pausing / Reactivating a Membership

At the end of a season, admins and dispatchers can pause a team member's membership instead of removing them. Pausing:

Excludes the member from auto-assignment suggestions.
Keeps their profile, certifications, and settings intact.
Shows them as "Paused" in the team list.

To pause, click Pause next to the member's name in the team list.

To reactivate, click Reactivate (admins and dispatchers only). The system sends a notification email letting the member know their membership has been reactivated.

Re-inviting a paused member: If you try to send an invitation to an email that already has a paused membership, the system automatically reactivates the existing membership and notifies the user — no new invitation is created.

11. Dispatch & Assignments

Manual Assignment

From the Dispatch page, each tour card includes a dynamic manual assignment form to add staff or vehicles:

Staff Selection: Select a staff member from the Staff dropdown. The list displays the person's First Name + Last Name and their certified dispatch capabilities (e.g., Noah UIOne (Driver / Guide)). Predefined Guides configured on the tour template are highlighted with ⭐ and prioritized at the top of the dropdown.
Smart Default Role Pre-selection: Upon selecting a staff member, the Role dropdown automatically pre-selects their primary certified role (Driver, Captain, Lead Guide, or Guide) and filters valid options based on their registered capabilities.
License & Category Vehicle Matching:
Driver: Enables the Vehicle dropdown and filters exclusively to Road vehicles (Bus, Van, Midi Coach, etc.) that match the driver's operator licenses.
Captain: Enables the Vehicle dropdown and filters exclusively to Marine vehicles (Panga, Catamaran, Skiff, etc.) that match the captain's marine licenses.
Guide / Lead Guide: Automatically disables the Vehicle dropdown with "(No vehicle needed)".
Vehicle dropdown options display capacity and category details (e.g., Coaster Bus 01 (30 pax · Road)).
Assigned & Overlapping Resource Exclusions: Staff members and vehicles already assigned to the current tour or to another overlapping tour on the same date are automatically excluded from the selection dropdowns.
Real-Time Live Dropdown Auto-Refresh: Clicking + Assign or removing an assignment automatically updates the manual assignment form in real-time via Turbo Streams without requiring a page reload. Assigned staff/vehicles disappear immediately upon assignment and re-appear if an assignment is removed.
Interactive Pre-Submit Rule Validation Warnings & Confirmations:
Oversized Vehicle Warning: If you select a vehicle with 40+ capacity for a small group (e.g., 8 passengers) when a smaller suitable vehicle (e.g., a 15-pax van) is available in your fleet, or if an under-capacity vehicle is chosen, an interactive warning prompt alerts you before submitting: > "Warning: This tour has 8 passengers, but you selected 'Custom Big Bus' (50 pax capacity) when a smaller suitable vehicle is available. Are you sure you want to proceed?"
Guide / Staff Requirement Over-Assignment Warning: If template rules specify required guide counts (e.g., 1 Lead Guide required) and that requirement is already fulfilled, attempting to assign an additional guide triggers a confirmation dialog: > "Rule Override Confirmation: The tour template rules specify 1 LEAD GUIDE(s), which are already assigned (1 currently assigned). Are you sure you want to assign an additional LEAD GUIDE and override the rule?" Clicking Cancel stops the submission; clicking OK confirms the manual rule override.

Removing an Assignment

You can remove an assignment by clicking the Remove button next to it. This is not allowed once the tour has started. Removing an assignment instantly restores the staff member and vehicle back into the manual assignment dropdown options.

Assignment Statuses

Draft — proposed by the auto-assignment system, pending your review. No notification is sent.
Confirmed — the assignment is active. The staff member receives a notification by email, Telegram, or WhatsApp (depending on their agency's enabled notification channels). They can Accept the assignment by clicking the link in the email or tapping the inline Accept button in Telegram or WhatsApp.
Rejected — the assignment was declined. This is kept for audit purposes.

Accepting Assignments (for Staff)

When you are assigned to a tour: 1. You receive a notification by email, Telegram, and/or WhatsApp with tour details. 2. Via email: Click the "Accept Assignment" button in the email — you will see a summary of the tour. Click Accept. 3. Via Telegram or WhatsApp: Tap the "✅ Accept" button on the notification message — the bot/service confirms your acceptance. 4. A confirmation email is sent to you with a calendar invite (.ics) you can add to Google Calendar, Outlook, or Apple Calendar. 5. Your dispatcher sees a live notification that you accepted.

Compensation Type

Each assignment tracks whether the staff member is paid on a Gig (flat fee per tour) or Hourly basis. The compensation type is inherited from the tour's default setting but can be overridden per assignment.

Freelance staff show a purple Freelance badge next to their name. Dispatchers and admins can click the ⏱ Hourly or 💰 Gig badge to toggle the compensation type for that assignment.
Employees and contractors do not show the compensation badge — their compensation is managed through your agency's payroll system.

12. Auto-Assignment & Optimization

PragmaticTours can automatically suggest the best combination of vehicles and staff for your tours. This saves time and helps you use your resources efficiently.

Optimizing a Single Tour

On any tour card, click "Auto-Assign". The system will:

Analyze your fleet — check which vehicles are available (not in maintenance, not already assigned elsewhere).
Select the best vehicles — it picks vehicles that have enough seats for your passengers, while using the fewest vehicles possible and minimizing wasted seats.
Select the best staff — based on:
Required roles (lead guide, guide, driver, captain).
Language coverage — staff languages are matched to passenger languages from the manifest.
Licenses — drivers and captains must hold the correct license for the vehicle.
Availability — no time-off blocks or scheduling conflicts.
Preferred operator — if a vehicle has a preferred driver or captain, they are suggested first.

Example: You have a tour with 20 passengers who speak English and French. Your fleet has one bus (40 seats), one van (15 seats), one panga (10 seats), and another panga (10 seats). You have one bilingual lead guide who speaks English and French, and one English-only guide.

The system will: - Suggest the van (15 seats) + one panga (10 seats) = 25 total seats, instead of using the bus (40 seats) which would waste 20 seats. - Suggest the bilingual lead guide for both languages, instead of assigning two separate guides.

Optimizing an Entire Day

On the Dispatch page, click "Optimize Day". The system analyzes ALL tours on that date and proposes assignments across all of them, making sure: - Each vehicle is only used on one tour per day. - Each staff member is only assigned to one tour at a time.

This is useful when you have multiple tours on the same day and want the best overall use of your fleet and staff.

Reviewing Proposals

All auto-assignments are created as Draft — nothing is final until you approve it. You will see a panel with all proposed assignments:

Accept each proposal individually, or use "Accept All" to confirm everything at once.
Reject proposals that don't work for you, or click "Reject All" to clear all draft suggestions at once.
Rejection Safety: Clearing/rejecting draft proposals bypasses operational constraint checks (such as location matching), guaranteeing that rejecting drafts always succeeds cleanly and never gets stuck.
Once accepted, the assignment becomes Confirmed and notifications are sent.

Important Notes

Auto-assignment is a suggestion tool. You can always override it by making manual changes.
The system never assigns a vehicle or person that is blocked by maintenance or has a scheduling conflict.
If no solution is found (e.g., not enough vehicles for all tours), the system will propose what it can and leave the rest for manual assignment.
If a tour template has no resource rules defined, the system cannot auto-assign anything for that tour. It will show a warning message: "No resource rules defined on this template. Please add rules or assign manually." Define rules in the template's detail page or assign staff and vehicles manually.

Optimization Modes: Resources vs Cost

The system offers two optimization modes. You will see two sets of buttons on the Dispatch page:

Button	Mode	Goal
⚡ Auto-Assign / ⚡ Optimize Day / ⚡ Optimize Multi-Day	Minimize Resources (default)	Use the fewest vehicles and staff possible, with least wasted seats.
💰 Auto-Assign (Cost) / 💰 Optimize Day (Cost) / 💰 Optimize Multi-Day (Cost)	Minimize Cost	Use the cheapest combination of vehicles and staff that meets all requirements.

Both modes respect all the same constraints — availability, licenses, hours, language coverage, and resource rules. The only difference is how choices are made among candidates that pass every filter.

Staff continuity vs. cost: When optimizing a multi-day tour, staff continuity always wins over cost. The tiebreaker hierarchy is: 1. Language/role score 2. Was this person assigned on a previous day of the same multi-day tour? (preferred) 3. Staff cost (cost mode only) 4. Hours worked that day 5. Name (alphabetical)

This means if the cheapest guide for Day 2 is a different person than Day 1's guide, the system will keep the Day 1 guide — continuity is prioritized over saving money. Cost optimization only affects which guide is chosen when there is no continuity preference (e.g., first day of a multi-day tour, or a single-day tour).

When to Use Each Mode

Minimize Resources — Use when you want to keep your fleet usage low and avoid dispatching more vehicles than necessary. Best when vehicle availability is tight and you need to reserve capacity for other tours.
Minimize Cost — Use when you have a variety of vehicle and staff options at different price points and want to minimize payout costs. A small cheap van may be preferred over a large luxury bus, even if it means using more than one vehicle.

How Cost Optimization Works

Vehicles: Each vehicle's total cost is the greater of hourly_cost × tour_duration and daily_cost (whichever is higher). The cost per seat is then total_cost ÷ capacity. The system picks vehicles with the cheapest seats first, regardless of size. This means it might choose two small cheap vans over one large expensive bus if the vans are cheaper per passenger, and it respects the vehicle's daily minimum cost even if the tour is short.

Staff: Staff cost is calculated as: - Gig rate (flat fee per tour) for gig-based compensation. - Hourly rate × tour duration for hourly-based compensation.

Among candidates with equal language coverage and role qualifications, the cheapest staff member is chosen first.

Example: You have a tour with 20 passengers. Your fleet options are: - Bus A: 50 seats, $100/hr ($2.00 per seat per hour) - Bus B: 30 seats, $80/hr ($2.67 per seat per hour) - Van: 15 seats, $50/hr ($3.33 per seat per hour)

In Resources mode, the system picks the smallest sufficient vehicle (Van + Bus B = 2 vehicles, minimal waste). In Cost mode, the system picks the cheapest seats first (Bus A alone — $2.00/seat is cheapest, even though it's the largest).

Conflict Resolution & Tie-Breaking Priority

When multiple staff members could fill a role, the system resolves conflicts using the following decision hierarchy. Each step narrows the pool until only one candidate remains.

For Guides (Lead Guide & Guide)

Priority	Rule	What Happens
1	Location match	If the tour has a location set, only guides who serve that location (or flexible guides with no restricted locations) are eligible.
2	Language coverage	Staff whose spoken languages overlap with the tour's required languages are preferred. A staff member with no languages set is treated as flexible — they can be assigned but are not chosen over someone with a documented language match.
3	Predefined guide priority	Among candidates matching language requirements (or for general guide slots), guides configured as Predefined Guides on the tour template are prioritized. A predefined guide without the required language cannot displace a guide needed for language coverage.
4	Lead-guide qualification	When looking for a universal guide (someone who speaks ALL required languages), a person who can act as lead guide is preferred over one who can only guide.
5	Multi-day continuity	When optimizing multi-day tours, the staff member previously assigned to earlier days of the tour is prioritized.
6	Hours worked	Among equally qualified candidates, the one with fewer hours already assigned on that day is chosen. This distributes workload evenly and avoids pushing anyone into overtime.
7	Name (alphabetical)	As a final deterministic tie-breaker, the staff member whose name comes first alphabetically is chosen.

For Drivers & Captains

Priority	Rule	What Happens
1	License match	The staff member must hold the correct operator license for the vehicle. Staff without the required license are excluded entirely.
2	Hours compliance	Staff who would exceed their `max_daily_hours` or `max_weekly_hours` are excluded, even if they are the preferred operator.
3	Preferred operator	If the vehicle has a `preferred_operator_id` and that person is available, licensed, and within hours, they are assigned immediately.
4	Hours worked	Among remaining candidates, the one with fewer hours assigned that day is chosen.
5	Name (alphabetical)	Final deterministic tie-breaker.

For Vehicles

Priority	Rule	What Happens
1	Fewest vehicles	The system first minimizes the total number of vehicles needed (CP-SAT solver) or uses best-fit bin packing (greedy fallback).
2	Least wasted capacity	Among solutions with the same number of vehicles, the one with the smallest total capacity (least empty seats) is chosen.

Cost Mode Tie-Breaking

When you use the 💰 Minimize Cost mode, the tie-breaking rules above change at two levels:

Vehicles: Instead of minimizing vehicle count and wasted capacity, the system minimizes total monetary cost (hourly_cost × tour_duration). It may choose more vehicles if they are collectively cheaper.

Staff (guides, drivers, captains): After language coverage, a new tie-breaker is inserted:

Priority	Rule	What Happens
3	Staff cost (cost mode only)	Among equally qualified candidates, the one with the lower staff cost (gig rate or hourly rate × duration) is chosen.

This means the full guide priority in cost mode becomes: language coverage → lead-guide qualification → staff cost → hours worked → name. And the full operator priority becomes: license → hours → preferred operator → staff cost → hours worked → name.

What Happens When No One Is Available

If no eligible staff member can be found (all are over hours, all lack licenses, all already assigned), the system records a failure in the optimization result and leaves that slot empty for manual assignment. You will see these failures listed in the optimization results panel.

Day-Scope Protection

When you run "Optimize Day", the system tracks every staff assignment across all tours on that date. A staff member assigned to the morning tour will not be proposed for the afternoon tour if there's a time overlap, even if each tour individually would consider them available. This prevents double-booking across your entire day.

Language Validation

When a staff member is assigned to a tour (either by the optimizer or manually), the system verifies that the assigned staff member's spoken languages overlap with at least one of the tour's passenger languages. If the staff member has languages set but none match the tour, the assignment is rejected with an error message. This ensures that a bilingual tour never gets an English-only guide.

This validation does not apply to staff with no languages set (they are considered flexible) or to non-guide roles (drivers, captains).

Optimizing a Multi-Day Tour

If you have a multi-day tour (with multiple daily child tours linked to a parent), you can optimize all days at once. On the parent tour card, next to the "Multi-Day (X days)" badge, you will find:

⚡ Optimize Multi-Day — Runs resource-minimizing optimization on every child tour of the multi-day parent.
💰 Optimize Multi-Day (Cost) — Runs cost-minimizing optimization on every child tour.

When you click either button, the system: 1. Optimizes each child tour independently, following its own template's resource rules. 2. Prefers the same staff (guides, drivers, captains) across consecutive days when they are available, providing consistency for your guests. 3. Collects all proposals into a single parent panel grouped by day.

This is more efficient than optimizing each day individually, especially for tours spanning 3+ days where you want the same guide throughout.

Understanding Unmet Requirements

When the system cannot fulfill every requirement, it records the failures and displays them as a warning banner at the top of the draft proposal panel. For example:

⚠️ Some requirements could not be met - Driver for Mercedes 500 1: No available driver (licensed, within hours, not already used) - Captain for Ocean Panga Boat: No available captain (licensed, within hours, not already used)

These warnings appear when: - No staff member with the required role is available on that date (scheduling conflicts, time-off blocks). - No staff member has the correct license for the vehicle. - All candidates would exceed their daily or weekly hour limits. - There are not enough qualified people for the number of vehicles (e.g., 2 pangas but only 1 captain).

The unfilled slots are left empty for manual assignment. You can use the manual assignment form below the draft panel to add staff or vehicles yourself.

13. Notification Engine & Multi-Channel Communications

PragmaticTours includes a built-in, real-time notification engine designed specifically for tour agency logistics. It connects dispatchers, tour agents, guides, drivers, captains, and external suppliers through three delivery channels: Email, Telegram Bot, and WhatsApp Cloud API (Meta).

Notification Channels by Subscription Tier

Basecamp (Free): Includes Email Notifications Only.
Voyage (Pro): Includes Email + your choice of WhatsApp OR Telegram Notifications (1 active instant messaging channel).
Expedition (Advanced): Includes Email + WhatsApp AND Telegram Notifications (both instant messaging channels active simultaneously).

Integration with Tour Dispatch, Agents, Guides & Drivers

1. Automated Tour Assignment Invitations

When an admin, dispatcher, or the auto-assignment optimization engine assigns a staff member (lead guide, guide, driver, or captain) to a scheduled tour: - The system automatically triggers an outbound notification via all enabled channels configured for that staff member. - Message Content: Tour Name, Pickup Date & Time, Pickup Location/Pier, Passenger Count, Language, Vehicle Name, and Special Instructions.

2. Interactive Accept / Decline Workflow for Drivers & Guides

Field staff members do not need to log into the web dashboard to confirm their work. They can interact directly with notifications: - Via Email: - Receives an HTML email containing Accept Assignment and Decline Assignment buttons. - Clicking Accept Assignment opens a confirmation page displaying the tour summary. Upon confirmation, the system generates an .ics calendar file for Google Calendar, Apple iCal, or Microsoft Outlook. - Via Telegram Bot: - Receives a real-time message card in Telegram with native inline ✅ Accept / ❌ Decline keyboard buttons. - Tapping ✅ Accept immediately updates the assignment status to confirmed in the database without opening a browser. - Via WhatsApp Cloud API (Meta): - Dispatches Meta-approved UTILITY interactive messages (tour_assignment template) with native quick-reply buttons (✅ Accept / ❌ Decline). - Tapping ✅ Accept sends an instant webhook back to PragmaticTours to register acceptance.

3. Real-Time Live Alerts for Dispatchers & Agents

When a driver or guide accepts or declines an assignment, the top-bar Notification Bell on the dispatcher dashboard flashes a red badge counter.
The Visual Dispatch Calendar updates in real time via Turbo Streams (ws/SSE), turning the assignment badge green (Accepted) or red (Declined), allowing dispatchers to re-assign declined tours immediately.

4. Automated Cancellation & Reschedule Notifications

Tour Cancellations: When an agent or dispatcher cancels a tour, an automated cancellation alert is dispatched immediately to all assigned drivers, guides, and captains via Email, Telegram, or WhatsApp so staff do not travel unnecessarily to pickup points.
Tour Reschedules: Changing a tour's date, pickup time, or pickup location automatically dispatches a reschedule alert containing old vs. new assignment details to all assigned team members.

5. External Supplier & Pool Unit Notifications

When third-party pool vehicles or supplier equipment units are assigned to tours, WhatsApp/Email notifications are automatically dispatched to the designated Supplier Representative containing vehicle pickup times and manifest counts.

Staff Setup: Linking Communication Channels

Email Notifications

Email notifications are enabled automatically using the physical email address registered under your staff profile (/settings/profile).

Telegram Connection (`/settings/telegram`)

(Visible when Telegram notifications are enabled by your agency) 1. Go to User Settings > Telegram Connection. 2. Click Connect to Telegram to generate a single-use pairing URL (e.g. https://t.me/YourAgencyBot?start=XYZ123). 3. Open the link in Telegram and start the bot. Once paired, real-time assignment cards with inline buttons will arrive directly in your Telegram chat.

WhatsApp Connection (`/settings/whatsapp`)

(Visible when WhatsApp notifications are enabled by your agency) 1. Go to User Settings > WhatsApp Connection. 2. Click Generate Pairing Code to produce a 6-digit code or direct wa.me verification link. 3. Send the 6-digit code to your agency's official WhatsApp Business number. A green Connected badge will verify connection. 4. Click Send Test Message to verify delivery.

Agency Administration & Meta WhatsApp Management (Admins Only)

Admins configure notification settings under Settings > Account Settings (/settings/account).

1. Channel Activation

Toggle enabled channels under Notification Channels: Email, Telegram, and WhatsApp.

2. Telegram Bot Configuration

Create a bot using @BotFather on Telegram and copy the API token.
Enter Bot Token and Bot Username in Agency Account Settings.
Click Register Webhook to connect PragmaticTours to Telegram.

2.1. Telegram Tour Catalog & Conversational Booking Bot (`telegram_bookings`)

When the telegram_bookings feature is enabled for your agency account (available in Advanced plan or as an add-on): - Tour Catalog Browsing: Travelers send /catalog or /tours to receive an interactive inline keyboard menu listing active tours with prices. - Real-Time Availability Queries: Natural language queries (e.g. "Is tour GAMBOA available on 2026-10-15?") check tour capacity, vehicle seats, and pricing in real time. - Passenger Manifest Collection & ICS Calendar Invites: Collects passenger lists via interactive chat steps, creates Booking (source: "telegram"), schedules calendar tours, appends passengers to TourPassenger manifest, and automatically dispatches an .ics calendar file attachment alongside instant Telegram booking confirmations.

3. Meta WhatsApp Cloud API Configuration

Embedded Signup: Click Connect with Meta to authenticate your WhatsApp Business Account (WABA).
Manual Configuration: Enter your Permanent Access Token, Phone Number ID, and WABA ID.

4. Meta Message Template Management

Meta classifies WhatsApp templates into three categories: - UTILITY: Transactional operational messages (assignments, cancellations, reschedules). Fast approval (minutes), lower conversation cost, high deliverability. - MARKETING: Promotional campaigns and sales offers. - AUTHENTICATION: One-time passcodes (OTP).

5. Mapped System Events & Template Auto-Switching

PragmaticTours automatically maps system events to WhatsApp templates: - tour_assignment: Dispatched when staff members are assigned. Includes positional variables {{1}} (Tour Name), {{2}} (Pickup Time), {{3}} (Pickup Address) and ✅ Accept / ❌ Decline buttons. - tour_cancellation: Dispatched when a tour is cancelled. - tour_reschedule: Dispatched when tour date/time is updated. - whatsapp_linked: Confirmation when staff link their WhatsApp account. - booking_confirmation: Dispatched automatically to travelers when a tour booking is confirmed via WhatsApp or web. - booking_inquiry: Dispatched when a booking inquiry is received. - booking_reminder: Scheduled 24h prior to pickup for upcoming bookings.

6. Interactive WhatsApp Tour Catalog & Conversational Booking Engine (`whatsapp_bookings`)

When the whatsapp_bookings feature is enabled for your agency account (available as an add-on or in the Advanced subscription tier), PragmaticTours transforms your official WhatsApp number into an automated booking assistant separate from staff assignment notifications:

Interactive Tour Catalog: Travelers or travel agents send "catalog" or "tours" to receive an interactive WhatsApp menu listing your active tour offerings with prices per passenger.
Real-Time Availability Queries: Users can ask natural language questions (e.g. "Is tour GAMBOA available on 2026-10-15?"). The engine calculates real-time tour capacity, vehicle seat availability, and pricing.
Passenger Manifest Collection: Collects lead passenger info and full passenger list (names, age categories, special requests) via interactive steps or native Meta WhatsApp Flows.
Automated Tour Scheduling & Passenger Manifest Sync: Upon tapping "Confirm Booking", PragmaticTours automatically creates a Booking record (source: "whatsapp"), schedules the tour on the calendar if not already present, appends all passengers to the active TourPassenger manifest list, updates pax_count, and issues an instant WhatsApp booking confirmation with reference BOOK-xxx.

Admins can submit custom Meta templates under Settings > Account Settings. Once approved (status 🟢 APPROVED by Meta), PragmaticTours automatically switches to using the newest approved template version for all subsequent outbound notifications.

14. Passenger Manifests

You can upload passenger lists in CSV format. The system supports two formats:

Cruise Format

Typically used for cruise ship passengers coming ashore for tours. Columns may include: - Voyage number, ship name, tour code, passenger names, language, special needs.

Charter Format

Typically used for private charters or group bookings. Columns may include: - Flight number, tail number, total passengers, connecting tour code.

How to Import

Go to Manifests and click "Upload Manifest".
Select your CSV file. Optionally, set a Schedule Date if the file does not include dates.
The system will process the file and show you:
Valid rows — passengers that match an existing tour template.
Invalid rows — passengers that could not be matched (e.g., unknown tour code).
Resolve invalid rows by either:
Assign to an existing template — select a tour product from the dropdown next to the row and click "Assign". The row immediately becomes valid.
Create a new product — click "+ Create Missing Product" to open a new template form in a new tab, pre-filled with the missing code. After saving, click "Re-validate" to re-process the file.
You can also skip invalid rows — the Import button is always available when there are valid rows. Invalid rows are simply ignored. A note shows how many will be skipped.
Click "Import". The system will create tours and assign passengers to them based on the passenger counts.

Per-Tour Upload

You can also upload a manifest directly on a specific tour page. This is useful when you already know which tour the passengers belong to.

15. Equipment & Inventory

Warehouses

Create warehouses to store your equipment. Each warehouse has a name and address.

Adding Equipment

Go to Inventory and click "Add Item". Enter: - Name — e.g., "Snorkel Sets". - Warehouse — where it is stored. - Total Quantity — how many you have. - Notes — any additional information.

Deleting vs Disabling an Asset

When you remove an asset from inventory: - If the asset has no usage history or template rules, it is permanently deleted. - If the asset has usage history or is referenced by template rules, it is disabled instead. A "Disabled" badge appears in the inventory list, and the asset will no longer appear in checkout suggestions. - You can re-enable a disabled asset at any time from its detail page.

Checking Out Equipment

On a tour card, click to add equipment. Select the item and enter the quantity your team is taking. The available quantity will decrease automatically.

Checking In Equipment

When your team returns, log the quantity returned. If everything comes back, the available quantity is restored. If some items are missing, the system will send an alert to the admins and dispatchers.

Auto-Suggested Equipment

If your tour templates have equipment rules set up (e.g., "1 snorkel set per 2 passengers"), the system will suggest the right quantities when you open a tour.

16. Financial Reports

The Reports section (admins only) shows daily revenue, staff costs, vehicle costs, and net profit for your tours.

Accessing Reports

Click Reports in the sidebar (admins only).
By default, the current month is shown. Use the Previous Month / Next Month arrows to navigate.
For a custom date range, use the From and To date pickers and click Filter.

Report Columns

Column	Description
Date	The tour date.
Tour	The tour name.
Pax	Number of passengers.
Price/Pax	Price per passenger set on the tour.
Revenue	`Price/Pax × Pax` (tour revenue).
Staff Cost	Sum of staff assignment costs for the tour.
Vehicle Cost	Sum of vehicle costs for the tour.
Net	`Revenue - Staff Cost - Vehicle Cost`.

How Cancelled Tours Affect Reports

Cancelled tours are included in the Financial Report — they appear with a "Cancelled" badge, and all their values (Revenue, Staff Cost, Vehicle Cost, Net) are shown as $0.00 / —. This prevents cancelled tours from distorting the report with misleading revenue or profit calculations.

Note: Since revenue is set to $0.00, a cancelled tour that had confirmed assignments before cancellation does not inflate the report's totals. The Payable Report excludes cancelled tours entirely.

Exporting to CSV

Click the CSV button to download the current report as a CSV file, which you can open in Excel, Google Sheets, or any spreadsheet application. The CSV includes a total row at the bottom.

CSV Format: Columns are Date, Tour, Pax, Price/Pax, Revenue, Staff Cost, Vehicle Cost, Net — one row per tour, plus a final TOTAL row. Compatible with Excel, Google Sheets, QuickBooks, Xero, and most accounting software.

17. Payable Report

The Payable Report (admins only) shows a detailed breakdown of what needs to be paid — freelance staff compensation and vehicle costs — for a given period.

Accessing

Click Payable Report in the sidebar (admins only). By default, the current month is shown.

What's Included

Freelance staff — only freelancers are listed (employees and contractors are excluded since their compensation is handled through payroll). Shows the compensation method (Gig or Hourly), the rate, the hours worked (tour duration), and the total cost.
Vehicles — contracted vehicles assigned to tours are listed with their hourly cost, hours used, and total cost. Owned vehicles are excluded as they are company assets and do not incur accounts payable.
Insurance Suppliers — external insurance brokers and coverage providers are automatically included whenever a scheduled tour includes passenger insurance. The payable calculation multiplies the passenger manifest count by the per-pax insurance rate ($$ \text{Passengers} \times \text{Insurance Rate/Pax} $$).

Columns

Column	Description
Date	The tour date.
Tour	The tour name.
Name	Name of the freelance staff member, contracted vehicle, or insurance provider.
Type	Staff (Gig/Hourly), Vehicle, or Insurance.
Rate	Hourly or Gig rate for staff; hourly cost for vehicles; per-pax rate for insurance.
Hours / Units	Tour duration in hours for staff/vehicles, or passenger count (e.g. `24 pax`) for insurance.
Total	Total amount payable ($$ \text{Rate} \times \text{Hours} $$, flat Gig rate, or $$ \text{Pax} \times \text{Insurance Rate} $$).
Ownership	Owned, Contracted, or Supplier.

Exporting to CSV

Click the CSV button to download the report for any date range.

CSV Format: Columns are Date, Tour, Name, Type, Rate, Hours, Total, Ownership — one row per freelance staff assignment, contracted vehicle assignment, or insurance supplier line. Compatible with Excel, Google Sheets, QuickBooks, Xero, and standard accounting/payroll platforms.

What is included: Only confirmed assignments and active scheduled tours are included. Draft or rejected assignments and cancelled tours are excluded to prevent accidental payouts.

18. User Settings

User Settings are personal workspace settings accessible to all staff members by clicking your initials/avatar in the top-right bar of the user dropdown menu:

Profile Settings (`/settings/profile`)

Update your First Name and Last Name.
Choose your Preferred Interface Language (English, Spanish, Portuguese, French, or Dutch).
Manage your Contact Numbers (Cell phone, WhatsApp number with international country flag selector).

Telegram Connection (`/settings/telegram`)

(Only visible when Telegram notifications are enabled by your agency) 1. Click Connect to Telegram to generate a unique pairing link (e.g., https://t.me/MyAgencyBot?start=ABC123). 2. Send the link to your agency's Telegram bot. 3. Once linked, you will receive real-time assignment notifications with inline ✅ Accept / ❌ Decline buttons.

WhatsApp Connection (`/settings/whatsapp`)

(Only visible when WhatsApp notifications are enabled by your agency) 1. Click Generate Pairing Code to produce a 6-digit code or direct wa.me connection link. 2. Send the code to your agency's registered WhatsApp Business number. 3. Once verified, a green Connected badge appears showing your phone number. 4. Click Send Test Message to verify message delivery.

Change Password (`/settings/password`)

Update your login password by entering your current password followed by your new password.

Availability Settings (`/settings/availability`)

Set personal time-off blocks (vacations, medical appointments, personal days). These blocks automatically prevent the auto-assignment system from scheduling you on those dates.

Agency Switcher & New Agency Setup

If your account belongs to multiple tour agencies, click any agency name in the dropdown to instantly switch workspaces.
Click + Create New Agency to set up a new agency workspace under your user account.

19. Account Settings

Account Settings (Agency Administration) are accessible only to Admins via Settings in the left sidebar navigation (/settings/account).

Agency Information & Subscription Plan

Update your official Agency Name.
View current Subscription Plan tier, billing cycle, and feature limits.

Proposal & Pre-Invoice Branding

Customize client-facing documents generated by the Quotes Engine: - Proposal Header Banner (proposal_header_image): Upload an engaging visual header banner (PNG, JPG, WEBP) that appears at the top of client proposals and proposal notification emails. - Pre-Invoice Header Banner (pre_invoice_header_image): Upload a distinct commercial banner with billing and tax registration information for pre-invoices and proforma statements. - Agency Contact & Social Links: Configure contact phone number, public email, website address, and social profiles (Instagram, Facebook, LinkedIn) displayed on documents. - Plan-Based Watermarking: Accounts on the Basecamp (Free) plan automatically include the "Power by: https://pragmatictours.com" footer legend on all PDFs, web proposal canvases, and emails. Accounts on Voyage (Pro) or Expedition (Advanced) plans enjoy 100% white-label documents without watermarks.

Notification Channels

Enable or disable agency notification dispatch channels: Email, Telegram, and WhatsApp. Multiple channels can be active simultaneously depending on your plan.

Telegram Bot Configuration

Create a Telegram bot via @BotFather and obtain its API token.
Enter the Bot Token and Bot Username.
Click Register Webhook to connect the bot to PragmaticTours.

WhatsApp Cloud API Configuration

Connect with Meta (Embedded Signup): Click Connect with Meta to authorize your WhatsApp Business Account (WABA).
Manual Configuration: Enter your Permanent Access Token, Phone Number ID, and WABA ID.
Centralized Webhook Policy: Webhook URL, App Secret, and Webhook Verify Token are managed centrally at the platform infrastructure level.

WhatsApp Message Templates Management

When WhatsApp is enabled for your agency, admins manage Meta message templates from Settings > Account Settings (/settings/account):

1. Meta Template Categories & Advantages

Meta classifies all message templates into three distinct categories. Selecting the right category affects review speed, messaging costs, and deliverability:

Category	Purpose & Content	Advantages & Differences
`UTILITY`	Transactional, operational messages directly tied to an active booking, assignment, cancellation, or account link (e.g. tour assignments, reschedules, cancellations).	• Fast Review: Approved within minutes by Meta's automated systems. • Lower Cost: Lower messaging rate tier per conversation. • High Reliability: Extremely low risk of user block or spam reports because messages are purely operational. • No Opt-Out Mandate: Does not require marketing opt-out buttons.
`MARKETING`	Promotional messages, special offers, new tour announcements, seasonal packages, or customer re-engagement campaigns.	• Content Flexibility: Allows promotional language, discounts, call-to-action sales buttons, and marketing pitch copy. • Higher Cost: Higher pricing tier per conversation. • Stricter Review: Subject to stricter Meta content reviews and higher user report rates if sent unprompted.
`AUTHENTICATION`	One-time passcodes (OTP) and security verification codes for multi-factor login verification.	• Security Standardized: Purpose-built for security codes with instant copy-code buttons.

2. System Events & Notification Triggers

PragmaticTours automatically dispatches WhatsApp messages when specific system events occur:

System Event	Mapped `template_type`	Trigger Condition	Positional Variables & Content	Interactive Buttons
Tour Assignment	`tour_assignment`	Triggered automatically when a dispatcher or auto-assigner confirms a staff member assignment to a scheduled tour.	`{{1}}` Tour Name `{{2}}` Pickup Date & Time `{{3}}` Pickup Address	Interactive `✅ Accept` / `❌ Decline` buttons
Tour Cancellation	`tour_cancellation`	Triggered automatically when an admin or dispatcher cancels a scheduled tour.	`{{1}}` Tour Name `{{2}}` Date `{{3}}` Cancellation Reason	None
Tour Reschedule	`tour_reschedule`	Triggered automatically when a tour is rescheduled to a new date/time.	`{{1}}` Tour Name `{{2}}` Old Date `{{3}}` New Date & Pickup Time	None
WhatsApp Linking	`whatsapp_linked`	Triggered when a staff member successfully links their WhatsApp account.	`{{1}}` Staff Member Name `{{2}}` Agency Name	None
Booking Inquiry	`booking_inquiry`	Triggered when a traveler submits a booking inquiry via WhatsApp or web widget.	`{{1}}` Customer Name `{{2}}` Tour Name `{{3}}` Booking Date `{{4}}` Passenger Count	Interactive `📝 Complete Booking`
Booking Confirmation	`booking_confirmation`	Triggered automatically when a tour booking is confirmed via WhatsApp or agency dispatch.	`{{1}}` Customer Name `{{2}}` Tour Name `{{3}}` Date & Pickup Time `{{4}}` Passenger Count `{{5}}` Pickup Address	Interactive `View Ticket/Voucher`
Booking Reminder	`booking_reminder`	Scheduled 24h prior to pickup for confirmed tour bookings.	`{{1}}` Customer Name `{{2}}` Tour Name `{{3}}` Date & Time `{{4}}` Pickup Address	None
Chat Reply	`chat_reply`	Triggered during interactive chat exchanges between staff/customers and the WhatsApp service.	`{{1}}` Response Message	None

3. Meta Formatting & Approval Requirements

All WhatsApp templates must be reviewed and approved by Meta before they can be used to send outbound messages.
Positional variables must start at {{1}} and increase sequentially ({{1}}, {{2}}, {{3}}).
Mandatory sample values must be provided for every variable.

4. Creating Default Templates

Select a language and click Create Default Templates to submit pre-formatted standard templates (tour_assignment_v1, tour_cancellation_v1) to Meta.

5. Creating Custom Templates & Mapping System Events

Expand Create New Template under Settings > Account Settings.
Template Name: Unique lowercase string accepted by Meta (e.g. caribbean_adventure_invite_2026).
System Event / Purpose: Select the target system event from the dropdown (e.g. Tour Assignment). This maps your custom Meta name directly to internal system triggers (template_type: "tour_assignment").
Body & Variables: Enter message text using sequential positional variables ({{1}}, {{2}}, {{3}}).

6. Overwriting & Custom Template Lifecycle

Once Meta approves the custom version (status 🟢 APPROVED), PragmaticTours automatically switches to using the latest approved template version for all subsequent outbound notifications.

API Keys (Admins Only)

Admins can generate API keys to allow external systems to interact with your PragmaticTours data programmatically via Settings > API Keys (/api_keys).

Account Cancellation & Data Export

Any workspace member can request account cancellation from Settings (/settings/account). Scroll to Cancel Account: - Triggers a complete CSV data export (profile, tours, passengers, vehicles, assignments). - Grants a 60-day grace period during which you retain access and can restore your workspace or download your data export.

20. API Reference (v1)

PragmaticTours provides a REST API for external systems (CRMs, booking engines, website widgets, OTAs, custom integrations) to manage tour, template, and booking data programmatically. All endpoints return JSON.

Authentication

Requests can be authenticated via: - API Key: Authorization: Bearer pt_your_api_key_here (generate at Settings > API Keys). - Account Token Header: X-Account-Token: your_account_slug

Base URL

https://youragency.pragmatictours.com/api/v1

Endpoints Overview

Method	Path	Description
`GET`	`/api/v1/tour_templates`	List all active tour templates (to select template IDs)
`GET`	`/api/v1/tour_templates/:id`	Get details for a single tour template
`POST`	`/api/v1/bookings`	Create a new booking (`pending` or `confirmed`)
`PATCH`	`/api/v1/bookings/:id`	Update booking status (`confirmed`, `cancelled`, `pending`)
`GET`	`/api/v1/bookings/:id`	Get details for a single booking
`GET`	`/api/v1/bookings`	List all bookings
`GET`	`/api/v1/tours`	List tours (with optional filters)
`GET`	`/api/v1/tours/:id`	Get a single tour with full details
`POST`	`/api/v1/tours`	Create a new tour
`GET`	`/api/v1/me`	Check session status (used by mobile app)

Tour Templates API

Use GET /api/v1/tour_templates to list all available tour templates. This enables external booking systems to query available tour products and obtain their id or code prior to placing a booking.

curl -H "X-Account-Token: company-a" \
  https://youragency.pragmatictours.com/api/v1/tour_templates

Bookings API & Integration Rules

[!IMPORTANT] Payment Gateway Policy: PragmaticTours does NOT process payments or include payment gateway handling. Operators process payments via their external payment processor (Stripe, PayPal, bank transfer, POS) and set the booking status to "confirmed" upon receiving payment.

[!NOTE] Tour Schedule & Manifest Integration: - Setting status to "confirmed" automatically creates and schedules a tour on the dashboard for that date (if not already existing). - Confirmed bookings automatically add all lead customer and passenger details to the tour's Passenger Manifest. - Pending bookings ("pending") do not schedule tours on the dashboard until confirmed.

Create a Booking (Example)

curl -X POST https://youragency.pragmatictours.com/api/v1/bookings \
  -H "Content-Type: application/json" \
  -H "X-Account-Token: company-a" \
  -d '{
    "tour_template_id": 1,
    "booking_date": "2026-10-15",
    "status": "confirmed",
    "customer": {
      "full_name": "Jane Doe",
      "email": "jane.doe@example.com",
      "phone": "+1 555-0123",
      "language_preference": "en"
    },
    "passengers": [
      { "passenger_name": "Jane Doe", "age_category": "adult" },
      { "passenger_name": "John Doe", "age_category": "adult" }
    ]
  }'

Update Booking Status (Example)

curl -X PATCH https://youragency.pragmatictours.com/api/v1/bookings/101 \
  -H "Content-Type: application/json" \
  -H "X-Account-Token: company-a" \
  -d '{
    "booking": {
      "status": "confirmed"
    }
  }'

List Tours

GET /api/v1/tours

Optional query parameters:

Param	Type	Description
`from`	date	Filter by date range start (e.g. `2026-08-01`)
`to`	date	Filter by date range end
`template_id`	integer	Filter by tour template
`status`	string	Filter by status (`scheduled`, `in_progress`, `completed`, `cancelled`)

Example:

curl -H "Authorization: Bearer pt_your_key" \
  "https://youragency.pragmatictours.com/api/v1/tours?from=2026-08-01&to=2026-08-31"

Get a Tour

GET /api/v1/tours/:id

Returns the tour with all fields. Multi-day tours include a child_tours array.

Create a Tour

POST /api/v1/tours
Content-Type: application/json

Single-day example:

{
  "tour": {
    "tour_template_id": 3,
    "pax_count": 20,
    "date": "2026-08-20",
    "pickup_time": "08:00",
    "pickup_address": "Hotel Lobby",
    "transit_duration_minutes": 30,
    "price_per_pax": 75.0
  }
}

Multi-day example (creates child tours automatically from template plans):

{
  "tour": {
    "tour_template_id": 7,
    "pax_count": 15,
    "start_date": "2026-09-10",
    "end_date": "2026-09-13"
  }
}

Field	Single-day	Multi-day	Auto-filled from template
`tour_template_id`	Required	Required	—
`pax_count`	Required	Required	—
`date`	Required	—	—
`start_date`	—	Required	—
`end_date`	—	Required	—
`pickup_time`	Optional	—	Yes
`pickup_address`	Optional	—	Yes
`transit_duration_minutes`	Optional	—	Yes
`price_per_pax`	Optional	—	Yes
`category`	Optional	Optional	Auto-detected from template
`compensation_type`	Optional	—	Defaults to `gig`

Error Responses

Status	Meaning
`400`	Bad request — missing required parameter
`401`	Unauthorized — missing or invalid API key
`404`	Not found — resource does not exist
`422`	Unprocessable entity — validation errors

Error bodies contain a JSON object with an error key. Depending on the error type, the value may be a string or an array of strings:

400 Bad Request: { "error": "param is missing" } (string)
401 Unauthorized: { "error": "Invalid or revoked API key" } (string)
422 Validation Error: { "error": ["Tour template is required", "Pax count must be greater than or equal to 0"] } (array)

Destination Management Company (DMC) Operations

1. Reseller & External Tour Fulfillment

Fulfillment Types: Tour templates and scheduled tours support fulfillment_type (in_house for internal fleet/guides or reseller for outsourced services via external suppliers).
Tour Templates for Resold Products: When creating or editing a TourTemplate in Product Catalog, select Fulfillment Type: Reseller (External Supplier) in Step 1. Optionally assign a Default Supplier to automatically pre-assign external activity providers or charter boat vendors.
Auto-Assignment Protection: Reseller tours automatically bypass vehicle/driver assignment rules and HOS optimizers, eliminating internal resource conflicts.
Dispatch UI Visuals: Reseller tours display distinct slate styling (bg-slate-50 border-l-4 border-slate-400 text-slate-800) with supplier badges on the Visual Dispatch dashboard.

2. External Supplier Management & Service Vouchers

Supplier Directory: Access Suppliers & External Providers directly from the sidebar navigation (under Fleet Manager / Catalog).
CRUD Management: Create, edit, and categorize external suppliers (charter boats, transport contractors, guide syndicates, restaurants/caterers, insurance brokers, hotels) along with contact info, WhatsApp number, emergency contacts, default net rates, and voucher delivery preferences (WhatsApp or Email).
Direct WhatsApp Chat: Supplier phone numbers support direct click-to-chat links (wa.me) with international country flag formatting for instant coordinator messaging.
Automated Vouchers: Generate digital ServiceVoucher records (VOUCH-XXXXXXXX) via Email or WhatsApp. Vouchers follow a pending → confirmed / rejected lifecycle.

3. B2B Agency & Agent Customer Hierarchy

Adding a B2B Agency: From the Customers menu (/customers), click Add Customer, set Customer Type to Reseller (Commission Agent), configure commission percentage and pricing tier, and save.
Customer Directory Filters: Use the sub-navigation tabs on the Customers index page to switch between All Customers, B2B Agencies & Resellers, and Standard Guests & Passengers.
Customer Types: Customers can be classified as standard (individual passengers or sub-agents) or reseller (b2b agencies/commission agents).
Parent Agency Linking: When creating or editing a customer/agent, select their Parent Agency (agency_id) and Pricing Tier (gross_markup or net_wholesale).
Passenger List Exclusion: Reseller agency customers are excluded from tour passenger counts and manifest seat allocations, ensuring accurate headcount optimization.

4. Hotel Supplier Workflow, Room Breakdown & Rooming Manifests

Hotel Supplier Setup: Create hotel partners in Suppliers & External Providers with Category: Hotel (e.g., Gamboa Rainforest Resort, JW Marriott Panama). Specify their reservation contact email, WhatsApp number, and default net room rate (default_net_rate, e.g., $120.00/night). Contact details are delegated to prevent field duplication.
Accommodation & Room Type Catalog:
Tie Accommodation records (overnight locations and pickup points) to their parent Hotel Supplier (supplier_id).
Configure RoomType categories for each accommodation (e.g., Deluxe King, Double Queen Suite, Executive Ocean Suite) with max_occupancy, bed_configuration, default_net_rate, and currency.
Multi-Day Tour Template Accommodations:
Inside each day plan of a multi-day TourTemplate, optionally attach overnight lodging details via the Overnight Accommodation panel.
Select the preferred RoomType, Meal Plan (Room Only, Bed & Breakfast, Half Board, Full Board), and Room Count.
Room Breakdown & Pricing on Service Vouchers:
When confirming a multi-day package or hotel stay, PragmaticTours generates digital ServiceVoucher records (VOUCH-XXXXXXXX) sent via WhatsApp or Email to the hotel's reservation desk.
Vouchers automatically detail room type breakdowns, check-in/out times, guest passenger counts, and total guaranteed net rates.
Rooming Manifest Export:
Dispatchers can download structured CSV Rooming Manifests directly from any tour card on the dispatch dashboard (/tours/:id/rooming_manifest.csv).
Manifest exports detail night numbers, hotel supplier contact info, room types, meal plans, room counts, and rooming tags per passenger.
OR-Tools Dispatch Solver Coordinates Fallback:
Overnight lodging coordinates (latitude, longitude) are used by the OR-Tools auto-assignment solver as day-end destinations and morning start locations.
If lodging coordinates are omitted, the solver gracefully falls back to the day's activity location or depot coordinates with zero optimizer disruption.

5. Deposit Payment Milestones & Currency Awareness

Payment Milestones: Track deposit, second_payment, and final_balance milestones per booking with due dates and payment statuses (pending, paid, overdue).
Base vs Billing Currency: Supports dual-currency conversions (total_price_base, commission_amount_base) for international DMC operations.

Need Help?

If you have questions or run into issues, contact your agency administrator. They can manage your account, adjust your permissions, or help you with any workflow questions.

PragmaticTours User Manual

Table of Contents

1. Getting Started

Logging In

First Time

The Main Navigation

Top Bar

2. Your Dashboard

Choose a Date

What You See

Multi-Day Tours

Fleet Status

3. Calendar View

4. Managing Tours

Creating a New Tour

Single-Day Tour

Multi-Day Tour

Form Validation

Tour Statuses

Editing a Tour

Uploading a Manifest to a Tour

Cancelling a Tour

Rescheduling a Tour

5. Bookings & Customers

Overview

How Bookings Are Created

Integration with Tour Schedule & Dashboard

Customer Management

How to Add a B2B Agency / Partner Account

6. Quotes, Proposals & Pre-Invoices

Industry Foundation: What the Quotes Engine Is Based On

The Costing Waterfall Mathematical Engine

The 5-Stage Guided Quote Pipeline

Financial Health & Profitability Gauge

Step-by-Step: Creating and Building a Quotation

Step 1: Setting Up Trip Logistics (/quotes/new)

Step 2: Day-by-Day Itinerary Builder

1. Day Header and Quick Controls

2. Auto-Populating Days with Searchable Tour Templates

3. Managing Line Items (QuoteItem)

4. Lodging & Room Selection

5. Adding Subsequent Days

Step 3: Commercial Calculation & Margin Setting Hub

Client Documents: Proposal vs. Pre-Invoice

Client Delivery Methods

The Operations Bridge: Converting Quotes into Dispatched Tours

Downstream Financial & Operational Reporting

Customizing Proposal & Pre-Invoice Formats for Your Agency

1. Managing Templates in the Proposal Templates Module (/proposal_templates)

2. Styling Proposals with HTML and Tailwind CSS

3. Complete Dynamic Merge Tags Reference

Company & Header Tags

Quote Metadata & Client Tags

Financial & Rates Tags

Dynamic Rich Tables & Narrative Blocks

4. Agency Account Branding & Legal Setup (/settings/account)

5. Best-Practice Strategies to Make Proposals Irresistible

7. Product Catalog

The 4-Step Tour Template Wizard

Step 1: Basics & Route (and Photo Gallery)

Step 2: Resource Scaling Rules (The Math)

Step 3: Pricing, Services & Cost Breakdown

Step 4: Review & Live Profitability Waterfall

Perks & Consumables Catalog (/perks)

Multi-Day Packages

Template List & Maintenance

8. Fleet Management

Adding a Vehicle

Fleet Structure & Vendor Syndicates (Pooled Fleets)

Setting a Preferred Operator

Maintenance & Unavailability

Deleting vs Disabling a Vehicle

Importing Vehicles from a CSV

9. Locations & Operational Zones

Managing Locations

Linking Fleet Assets & Tour Logistics

Min / Max Passenger Capacity & Rich Itineraries

10. Team Management

Roles

Inviting a New Team Member

Step 1: Setting Up Trip Logistics (`/quotes/new`)

3. Managing Line Items (`QuoteItem`)

1. Managing Templates in the Proposal Templates Module (`/proposal_templates`)

4. Agency Account Branding & Legal Setup (`/settings/account`)

Perks & Consumables Catalog (`/perks`)

Telegram Connection (`/settings/telegram`)

WhatsApp Connection (`/settings/whatsapp`)

2.1. Telegram Tour Catalog & Conversational Booking Bot (`telegram_bookings`)

6. Interactive WhatsApp Tour Catalog & Conversational Booking Engine (`whatsapp_bookings`)