Supplier Agreements Configuration Guide

Payment Terms, Invoice Lines & Supplier Contracts

This guide provides comprehensive documentation for configuring Supplier Agreements in Kaptio. Supplier Agreements define the commercial terms between your organization and suppliers, including payment schedules, commission structures, and invoice timing.

What are Supplier Agreements?

Supplier Agreements are contracts that define how and when you pay suppliers for services included in tour packages. They control payment timing (deposits, balance, billback), commission rates, and which services are covered by each agreement.

Key Capabilities

• Agreement Types: Net Rate or Commission-based contracts

• Payment Rules: Flexible deposit, balance, and billback timing

• Service Assignments: Link agreements to specific services, price categories, add-ons, or fees

• Automatic Invoice Lines: System generates invoice lines based on payment rules

• Due Date Calculation: Automatic calculation based on booking or travel dates

• Agreement Chaining: Automatic validity date management when agreements overlap

When to Configure Supplier Agreements

• New Supplier Onboarding: Setting up payment terms for a new supplier

• Contract Renewal: Creating new agreements when contracts are renegotiated

• Rate Changes: Adjusting commission rates or payment schedules

• Service Assignment: Linking agreements to specific services or price categories

IMPORTANT: Agreement → Payment Rules → Invoice Lines

Supplier Agreements are the master record that defines the relationship with a supplier. Payment Rules define when payments are due. Invoice Lines are automatically generated from booked itinerary items based on these rules. You do NOT create invoice lines manually. The system generates them when bookings are made, based on the active agreement and payment rules.

Data Model Architecture

Account (Supplier)
  │
  └── SupplierAgreement__c (Master-Detail)
        │   • Agreement Type (Net Rate / Commission)
        │   • Valid From / Valid To dates
        │   • Default Commission %
        │   • Brand / Channel restrictions
        │
        ├── PaymentRule__c (Master-Detail)
        │       • Type: Deposit %, Deposit Amount, Balance, Billback
        │       • Days: Number of days offset
        │       • Date Type: Booking Date or Travel Date
        │       • When: Before/After the date type
        │
        └── SupplierAgreementAssignment__c (Lookup)
                • Links agreement to:
                  - Service (Item__c)
                  - Price Category
                  - Add-on
                  - Fee

Itinerary__c (Booking)
  │
  └── Itinerary_Item__c
        │   • InvoiceTo__c → Supplier Account
        │
        └── SupplierInvoiceLine__c (Auto-generated)
                • PaymentRule__c reference
                • Due Date (calculated)
                • Cost / Commission amounts
                │
                └── SupplierInvoiceBooking__c (Groups by Supplier + Booking)

Key Objects Explained

Object	Purpose	Relationship
SupplierAgreement__c	The contract record - defines terms with supplier	Master-Detail to Account
PaymentRule__c	Individual payment terms (deposit, balance, billback)	Master-Detail to Agreement
SupplierAgreementAssignment__c	Links agreement to specific services/products	Lookup to Agreement
SupplierInvoiceLine__c	Individual payment line item (auto-generated)	Lookup to PaymentRule, ItineraryItem
SupplierInvoiceBooking__c	Groups invoice lines by supplier + booking	Parent of SupplierInvoiceLine

Before You Begin

Ensure the following are in place before configuring Supplier Agreements:

Requirement	Description	Where to Check
Supplier Account	Account record with Supplier record type	Accounts → Supplier record type
Services Created	Item__c records for services supplier provides	Items → Services tab
Price Categories	Price categories for the services (if applicable)	Service record → Price Categories
Brands/Channels	Business Unit and Channel configuration	Setup → Custom Metadata Types

Permission Requirements

Users configuring Supplier Agreements need: Edit access to Account (Supplier) records Create/Edit access to SupplierAgreement__c Create/Edit access to PaymentRule__c Create/Edit access to SupplierAgreementAssignment__c

How Supplier Payments Work in Kaptio

When a booking is made that includes services from a supplier, the system automatically generates invoice lines based on the active supplier agreement and payment rules.

Booking Created
       │
       ▼
System finds active Agreement for Supplier
       │
       ▼
Agreement Selection Criteria:
  • ValidFrom ≤ Today
  • ValidTo ≥ Today (or null)
  • Matching Brand/Channel
  • Service Assignment exists
       │
       ▼
Payment Rules Applied
       │
       ├── Deposit Rule (20% due 7 days after booking)
       │       └── Creates Invoice Line: Due [Booking Date + 7]
       │
       └── Balance Rule (80% due 14 days before travel)
               └── Creates Invoice Line: Due [Travel Date - 14]

Agreement Types

Type	Description	Use Case
Net Rate	You pay the supplier a net cost	Hotels, transport, fixed-price services
Commission	Supplier pays you commission on sales	Airlines, attractions with agency commission

What are Invoice Lines?

Supplier Invoice Lines represent individual payment obligations to suppliers. They are automatically generated when bookings are made and track amounts due, invoiced, and balance remaining.

Key Invoice Line Fields

Field	Description
Due Date	Calculated date when payment is due (based on payment rule)
Cost Due	Amount due to supplier in base currency
Cost Invoiced	Amount already allocated to supplier invoices
Balance Due	Remaining amount (Cost Due - Cost Invoiced)
Commission	Commission amount (for commission-type agreements)
Is Complete	True when fully invoiced/paid
Payment Rule Type	Type from payment rule (deposit, balance, billback)

Invoice Line Lifecycle

Created: When booking includes supplier service Due: Due date approaches based on payment rule Allocated: Line allocated to Supplier Invoice Complete: Fully invoiced and paid

Grouping Invoice Lines

Supplier Invoice Booking records group all invoice lines for a single supplier within a single itinerary (booking). This provides a consolidated view of supplier payments per booking.

Invoice Booking Rollups

Field	Calculation
Total Cost Due	Sum of all Cost Due from child invoice lines
Total Cost Invoiced	Sum of all Cost Invoiced from child invoice lines
Total Balance Due	Sum of all Balance Due from child invoice lines
Total Commission	Sum of all Commission from child invoice lines

How Due Dates are Calculated

Due dates are calculated based on the Payment Rule configuration:

Payment Rule Configuration:
  • Date Type: "Booking Date" or "Travel Date"
  • When: "After Booking Date", "Before Travel Date", "After Travel Date"
  • Days: Number of days offset

Examples:
  ┌─────────────────────────────────────────────────────────────┐
  │ Rule: 7 days AFTER BOOKING DATE                             │
  │ Booking: Jan 15                                             │
  │ Due Date: Jan 22 (15 + 7)                                   │
  └─────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────┐
  │ Rule: 14 days BEFORE TRAVEL DATE                            │
  │ Travel: Mar 1                                               │
  │ Due Date: Feb 15 (Mar 1 - 14)                               │
  └─────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────┐
  │ Rule: 30 days AFTER TRAVEL DATE (Billback)                  │
  │ Travel: Mar 1                                               │
  │ Due Date: Mar 31 (Mar 1 + 30)                               │
  └─────────────────────────────────────────────────────────────┘

Linking Invoice Lines to Supplier Invoices

When you create a Supplier Invoice and allocate invoice lines to it, the system creates allocation records that track the relationship.

Allocation Process

• Create Supplier Invoice record

• Select invoice lines to allocate

• System creates SupplierInvoiceAllocation__c records

• Invoice Line “Cost Invoiced” field updates

• When fully allocated, “Is Complete” becomes true

Partial Allocations

Invoice lines can be partially allocated across multiple invoices. The Balance Due field tracks the remaining amount.

Configuration Steps

Setting up a Supplier Agreement involves three main steps:

Step 1: Create Supplier Agreement
        │
        │   Account (Supplier)
        │       └── New Supplier Agreement
        │           • Agreement Type
        │           • Valid From / To
        │           • Brand / Channel
        │
        ▼
Step 2: Add Payment Rules
        │
        │   Payment Rules define WHEN payments are due:
        │       • Deposit (20% after booking)
        │       • Balance (before travel)
        │       • Billback (after travel)
        │
        ▼
Step 3: Assign to Services
        │
        │   Agreement Assignments link to:
        │       • Specific Services
        │       • Price Categories
        │       • Add-ons
        │       • Fees

Creating a New Agreement

Navigate to the Supplier Account record and create a new Supplier Agreement.

Required Fields

Field	Description	Example
Account	Supplier account (auto-populated)	Grand Hotel Partners
Agreement Type	Net Rate or Commission	Net Rate
Valid From	Agreement start date	Jan 1, 2026
Valid To	Agreement end date (optional)	Dec 31, 2026

Optional Fields

Field	Description
Default Commission	Default commission % for commission agreements
Brand	Restrict agreement to specific business unit
Channels	Restrict agreement to specific sales channels
Invoice Basis	Basis for supplier invoice calculation
Tax Exclusive Commission	Calculate commission excluding tax

Agreement Name Auto-Generation

The agreement name is automatically generated from the Valid From and Valid To dates, e.g., “Jan 2026 - Dec 2026”.

Payment Rule Types

Payment Rules define when and how much is due to the supplier.

Type	Description	Value Field
Deposit Percentage	Percentage of total cost due	% (e.g., 20)
Deposit Amount	Fixed amount due per booking/person	Amount (e.g., $500)
Balance	Remaining amount after deposits	N/A (calculated)
Billback	Full amount due after travel	N/A (100%)
Billback Self-Bill	Self-billing variant of billback	N/A (100%)

Timing Configuration

Field	Options	Example
Days	Number of days offset	14
Date Type	Booking Date, Travel Date	Travel Date
When	After Booking Date, Before Travel Date, After Travel Date	Before Travel Date

Payment Rule Validation

The system validates payment rules: At least one payment rule is required If only deposits: percentages must total 100% Only one Balance rule allowed Only one Billback rule allowed All rules must have valid Date Type and When values

Linking Agreements to Services

Agreement Assignments specify which services, price categories, add-ons, or fees are covered by the agreement.

Assignment Options

Assignment Type	Description	Use Case
Service	Assigns to entire service (all price categories)	All room types at a hotel
Price Category	Assigns to specific price category	Only deluxe rooms at a hotel
Add-on	Assigns to specific add-on	Airport transfers from supplier
Fee	Assigns to specific fee	Fuel surcharge from supplier

Assignment Priority

When a booking is made, the system looks for assignments in this order: Price Category assignment (most specific) Service assignment Add-on assignment Fee assignment

Agreement Status Validation

The system automatically validates agreements and sets the supplier account status.

Account Agreement Statuses

Status	Meaning
Active Agreement	Valid agreement exists for today’s date
Agreement Expiring Soon	Agreement Valid To date is approaching
No Agreement	No valid agreement exists
Invalid Agreement	Agreement has configuration errors

Common Validation Errors

• No Payment Rules: Agreement must have at least one payment rule

• Invalid Deposit Total: Deposit percentages must equal 100% if no balance rule

• Multiple Balance Rules: Only one balance rule allowed

• Multiple Billback Rules: Only one billback rule allowed

• Missing Date/When: All payment rules must have valid timing configuration

Example 1: Hotel with Deposit + Balance

Standard hotel agreement with deposit due after booking and balance before travel.

Agreement: "Jan 2026 - Dec 2026"
├── Type: Net Rate
├── Valid From: Jan 1, 2026
├── Valid To: Dec 31, 2026
│
├── Payment Rule 1: Deposit
│   ├── Type: Deposit Percentage
│   ├── Value: 20%
│   ├── Days: 7
│   ├── Date Type: Booking Date
│   └── When: After Booking Date
│
└── Payment Rule 2: Balance
    ├── Type: Balance
    ├── Days: 14
    ├── Date Type: Travel Date
    └── When: Before Travel Date

Example 2: Transport Billback

Transport provider paid after travel is complete.

Agreement: "2026 Transport Agreement"
├── Type: Net Rate
├── Valid From: Jan 1, 2026
│
└── Payment Rule: Billback
    ├── Type: Billback
    ├── Days: 30
    ├── Date Type: Travel Date
    └── When: After Travel Date

Example 3: Commission Agreement

Attraction partner with commission on ticket sales.

Agreement: "Attractions Commission 2026"
├── Type: Commission
├── Default Commission: 15%
├── Valid From: Jan 1, 2026
│
└── Payment Rule: Billback Self-Bill
    ├── Type: Billback Self-Bill
    ├── Days: 45
    ├── Date Type: Travel Date
    └── When: After Travel Date

Example 4: Fixed Deposit Amount

Cruise supplier requiring fixed deposit per person.

Agreement: "Cruise Partner 2026"
├── Type: Net Rate
├── Valid From: Jan 1, 2026
│
├── Payment Rule 1: Per-Person Deposit
│   ├── Type: Deposit Amount
│   ├── Value: $500
│   ├── Deposit Type: Per Person
│   ├── Days: 3
│   ├── Date Type: Booking Date
│   └── When: After Booking Date
│
└── Payment Rule 2: Balance
    ├── Type: Balance
    ├── Days: 60
    ├── Date Type: Travel Date
    └── When: Before Travel Date

Testing Your Configuration

After configuring a Supplier Agreement, test it with these steps:

• Verify Agreement Status: Check supplier account shows “Active Agreement”

• Create Test Booking: Book an itinerary with the supplier’s service

• Check Invoice Lines: Verify invoice lines are generated with correct:

  Due dates

  • Amounts

  • Payment rule references

• Verify Invoice Booking: Check Invoice Booking record shows correct totals

Common Test Scenarios

Scenario	What to Verify
Booking today, travel in 30 days	Deposit due date based on booking, balance due date based on travel
Booking today, travel tomorrow	Due dates may overlap or be in the past - verify handling
Multiple services from same supplier	Separate invoice lines per service, grouped by Invoice Booking
Different price categories	Correct assignment applied per price category

Common Issues and Solutions

Issue: No Invoice Lines Generated

Possible Cause	Solution
Agreement dates invalid	Check Valid From/To dates include booking date
No Assignment for service	Create Agreement Assignment for the service
No Payment Rules	Add at least one payment rule to agreement
Brand/Channel mismatch	Check agreement Brand and Channels match booking

Issue: Incorrect Due Dates

Possible Cause	Solution
Wrong Date Type	Verify Date Type is Booking Date or Travel Date as intended
Wrong When value	Check Before/After configuration
Days value incorrect	Verify number of days offset

Issue: Agreement Shows “Invalid”

Possible Cause	Solution
Missing payment rules	Add at least one payment rule
Deposit percentages don’t total 100%	Adjust deposit percentages or add balance rule
Multiple billback rules	Remove duplicate billback rules

Supplier Agreement Setup Checklist

Pre-Configuration

• ☐ Supplier Account exists with correct record type

• ☐ Services created and linked to supplier

• ☐ Price Categories configured for services

• ☐ Required permissions granted to users

Agreement Configuration

• ☐ Agreement created with correct type (Net Rate/Commission)

• ☐ Valid From date set

• ☐ Valid To date set (if applicable)

• ☐ Brand restriction set (if applicable)

• ☐ Channel restriction set (if applicable)

Payment Rules

• ☐ At least one payment rule created

• ☐ Deposit rule configured (if using deposits)

• ☐ Balance rule configured (if using deposits)

• ☐ Billback rule configured (if post-travel payment)

• ☐ Days, Date Type, and When values set correctly

• ☐ Agreement shows “Active Agreement” status

Assignments

• ☐ Agreement assigned to relevant services

• ☐ Price category assignments created (if needed)

• ☐ Add-on assignments created (if needed)

• ☐ Fee assignments created (if needed)

Testing

• ☐ Test booking created

• ☐ Invoice lines generated correctly

• ☐ Due dates calculated correctly

• ☐ Amounts calculated correctly

SupplierAgreement__c Fields

API Name	Type	Description
Account__c	Master-Detail	Supplier Account
AgreementType__c	Picklist	Net Rate, Commission
ValidFrom__c	Date	Agreement start date
ValidTo__c	Date	Agreement end date
DefaultCommission__c	Percent	Default commission rate
Brand__c	Lookup	Business Unit restriction
Channels__c	Long Text	Channel IDs (comma-separated)

PaymentRule__c Fields

API Name	Type	Description
SupplierAgreement__c	Master-Detail	Parent agreement
Type__c	Picklist	billback, deposit percentage, deposit amount, balance
Value__c	Number	Percentage or amount
Days__c	Number	Days offset
DateType__c	Picklist	booking date, travel date
When__c	Picklist	after booking date, before travel date, after travel date
DepositType__c	Picklist	per person, per booking

SupplierInvoiceLine__c Key Fields

API Name	Type	Description
DueDate__c	Date	Calculated due date
CostDue__c	Currency	Amount due to supplier
CostInvoiced__c	Currency	Amount allocated to invoices
BalanceDue__c	Currency	Remaining balance
IsComplete__c	Checkbox	True when fully invoiced
PaymentRule__c	Lookup	Source payment rule

Related Documentation

• Booking Wizard Options Guide - Setting up options and extras

• Supplier Management Outcome - Overview of supplier capabilities

Key Apex Classes

• SupplierAgreements.cls - Domain logic for agreements

• SupplierAgreementService.cls - Business rules and validation

• PaymentRules.cls - Payment rule domain logic

• PaymentRulesService.cls - Payment rule service methods

• SupplierInvoiceLines.cls - Invoice line processing

• SupplierInvoiceLineFactoryNew.cls - Invoice line generation

Lightning Components

• lwcSupplierAgreementModal - Create/edit agreements

• lwcSupplierAgreementAssignmentModal - Manage assignments