Skip to main content

Pricing, Fees & Revenue Rules - Version Mapping

Domain: Pricing, Fees & Revenue Rules First Introduced: V1.0 Last Updated: 2025-10-25

Version Introduction Timeline​

VersionStatusScopeDescription
MVP.0OUT OF SCOPENonePricing domain completely deferred
MVP.1OUT OF SCOPENonePricing domain completely deferred
V1.0PLANNEDFull ImplementationComplete dynamic pricing engine with quotes, fees, taxes, and revenue splits
V1.1FUTUREEnhancementsTax engine enhancement with Avalara integration
V1.2FUTUREAdvanced FeaturesGap night automation, promotional codes, rate templates
V2.0FUTUREAI FeaturesDynamic pricing AI integration
V2.1FUTUREInternationalMulti-currency, VAT/GST, international tax compliance
V3.0FUTUREEnterpriseWhite-label marketplace revenue sharing

MVP.0 - OUT OF SCOPE​

Status: Not Implemented Rationale: MVP.0 focuses on foundation (tenancy, authorization, supply, content). Pricing deferred to reduce initial scope.

Excluded Entities​

  • All pricing entities deferred

Excluded Features​

  • Quote generation
  • Rate plans and pricing rules
  • Fee structures
  • Tax calculation
  • Revenue splits
  • Dynamic pricing

Workaround​

  • Hardcoded rates (not database-driven)
  • Manual pricing outside system
  • Bookings not supported in MVP.0

MVP.1 - OUT OF SCOPE​

Status: Not Implemented Rationale: MVP.1 adds read-only booking awareness. Full pricing still deferred to V1.0.

Excluded​

  • All pricing functionality deferred to V1.0

V1.0 - FULL IMPLEMENTATION​

Status: Planned Target: Initial production release with booking capabilities

Core Entities (8)​

  1. RatePlan - Top-level pricing container

    • Base rates and pricing modifiers
    • Dynamic pricing configuration
    • Channel-specific plans
    • Priority-based selection

  2. RateRule - Conditional rate adjustments

    • Seasonal pricing
    • Length-of-stay discounts
    • Day-of-week pricing
    • Lead time adjustments
    • Occupancy-based pricing
    • Compound modes (additive, multiplicative, override)

  3. FeeRule - Additional charges

    • Cleaning fees
    • Pet fees
    • Service fees
    • Resort fees
    • Amenity fees
    • Taxable vs non-taxable fees
    • Mandatory vs optional fees

  4. TaxJurisdiction - Geographic tax authorities

    • Federal, state, county, city, district levels
    • Hierarchical relationships
    • Geographic boundaries
    • Filing requirements

  5. TaxRule - Tax calculation logic

    • Percentage and fixed taxes
    • Tiered tax structures
    • Exemption rules
    • Compound taxes
    • Marketplace facilitator rules

  6. SpaceTaxMapping - Property-to-jurisdiction links

    • Address-based mapping
    • Postal code resolution
    • Geo-coordinate mapping
    • Manual overrides

  7. RevenueRule - Payout distribution

    • Owner/manager/platform splits
    • Percentage and fixed amounts
    • Tiered commission structures
    • Channel-specific splits

  8. Quote - Immutable pricing snapshot

    • Rate plan snapshot preservation
    • Line-item breakdown
    • Daily rate tracking
    • Revenue split calculation
    • Expiration handling

Supporting Entities (3)​

  1. QuoteLineItem - Itemized charge breakdown
  2. QuoteDailyRate - Per-night rate details
  3. QuoteRevenueSplit - Revenue distribution breakdown

Key Features​

Quote Generation:

  • Real-time pricing calculation (<100ms target)
  • Rule-based rate evaluation
  • Fee application logic
  • Tax calculation
  • Revenue split computation
  • Immutable snapshots

Fee Types Supported:

  • Cleaning fee (fixed per stay)
  • Pet fee (per stay or per pet)
  • Extra guest fee (per guest per night)
  • Service fee (percentage of subtotal)
  • Processing fee (percentage of total)

Tax Calculation:

  • US state, county, city tax rates
  • Manual jurisdiction mapping
  • Percentage-based calculation
  • Basic exemptions (30+ night stays)
  • Platform collection tracking

Revenue Splits:

  • Simple percentage splits (e.g., owner 80%, platform 20%)
  • Fixed commission structures
  • Basis: gross or net
  • No tiered splits (deferred to V1.1+)

Dynamic Pricing:

  • Integration hooks defined
  • Manual rate updates only
  • Provider configuration stored
  • Actual integration deferred

Business Rules​

  1. Each Space must have at least one active RatePlan
  2. Quotes expire after validity period (24-48 hours)
  3. Rate plans immutable once quoted (versioning via snapshots)
  4. Tax calculations occur AFTER all fees applied
  5. Revenue splits must balance (tracked for future validation)
  6. Min/max rate constraints enforced
  7. All amounts stored in minor units (cents)

Database Objects​

Tables: 11 (RatePlan, RateRule, FeeRule, TaxJurisdiction, TaxRule, SpaceTaxMapping, RevenueRule, Quote, QuoteLineItem, QuoteDailyRate, QuoteRevenueSplit) Indexes: 25+ Constraints: 15+ Triggers: 1 (quote immutability)

API Endpoints​

  • POST /quotes - Generate quote
  • GET /quotes/:id - Retrieve quote
  • GET /rate-plans - List rate plans
  • POST /rate-plans - Create rate plan
  • PUT /rate-plans/:id - Update rate plan
  • GET /tax-jurisdictions - List jurisdictions
  • POST /space-tax-mappings - Map space to jurisdictions

Performance Requirements​

  • Quote generation: <100ms (target), <500ms (max)
  • Rate plan caching: 15-minute TTL
  • Tax jurisdiction caching: 24-hour TTL

Deferred to V1.1+​

  • Avalara MyLodgeTax integration
  • Gap night automation
  • Promotional codes
  • Multi-currency support
  • Tiered revenue splits
  • Channel-specific revenue overrides

V1.1 - TAX ENGINE ENHANCEMENT​

Status: Future Scope: Automated tax calculation and compliance

New Features​

  • Avalara MyLodgeTax Integration

    • Real-time jurisdiction resolution
    • Automated tax rate updates
    • Tax remittance tracking
    • Filing queue management

  • Enhanced Exemption Processing

    • Long-term stay exemptions
    • Military/government exemptions
    • Threshold-based exemptions

  • Tax Reporting

    • Multi-jurisdictional reports
    • Filing status tracking
    • Remittance automation

Impact​

  • Eliminates manual tax configuration
  • Ensures compliance accuracy
  • Reduces administrative burden

V1.2 - ADVANCED PRICING FEATURES​

Status: Future Scope: Competitive feature parity

New Features​

  • Gap Night Automation

    • Automatic pricing for orphan nights
    • Calendar optimization

  • Last-Minute Discounts

    • Automated discount rules
    • Inventory optimization

  • Promotional Codes

    • Discount campaigns
    • Promo code management
    • Usage tracking

  • Rate Templates

    • Quick setup templates
    • Bulk rate operations
    • Seasonal templates

Impact​

  • Feature parity with Guesty/Hostaway
  • Improved revenue optimization
  • Faster property onboarding

V2.0 - DYNAMIC PRICING AI​

Status: Future Scope: Revenue optimization through AI

New Features​

  • PriceLabs/Wheelhouse/Beyond Integration

    • Bi-directional API integration
    • Rate synchronization

  • AI-Powered Optimization

    • Demand forecasting
    • Competitor rate monitoring
    • Automated price adjustments

  • Revenue Analytics

    • Performance dashboards
    • Optimization recommendations
    • A/B testing support

Impact​

  • +10-20% revenue vs static pricing
  • Automated pricing decisions
  • Competitive market positioning

V2.1 - INTERNATIONAL EXPANSION​

Status: Future Scope: Global marketplace support

New Features​

  • Multi-Currency Support

    • FX rate management
    • Real-time conversion
    • Currency-specific pricing

  • VAT/GST Handling

    • European VAT compliance
    • Australian GST
    • Canadian tax rules

  • International Tax Compliance

    • EU, UK, Australia regulations
    • Cross-border payment splitting

Impact​

  • Global marketplace expansion
  • International property support
  • Regulatory compliance

V3.0 - ENTERPRISE FEATURES​

Status: Future Scope: Complex B2B partnerships

New Features​

  • White-Label Marketplace

    • Partner revenue sharing
    • Multi-tier commission structures

  • Affiliate Tracking

    • Referral commission tracking
    • Performance analytics

  • Advanced Revenue Splits

    • Tiered commission structures
    • Revenue caps and guarantees
    • Complex multi-party splits

Impact​

  • Support B2B partnerships
  • Marketplace business model
  • Enterprise-scale operations

Feature Availability Matrix​

FeatureMVP.0MVP.1V1.0V1.1V1.2V2.0+
Rate Plans❌❌✅✅✅✅
Rate Rules (Seasonal, LOS, etc.)❌❌✅✅✅✅
Fee Structures❌❌✅✅✅✅
Tax Calculation (Manual)❌❌✅✅✅✅
Tax Calculation (Avalara)❌❌❌✅✅✅
Quote Generation❌❌✅✅✅✅
Revenue Splits (Simple)❌❌✅✅✅✅
Revenue Splits (Tiered)❌❌❌✅✅✅
Gap Night Automation❌❌❌❌✅✅
Promotional Codes❌❌❌❌✅✅
Dynamic Pricing (Manual)❌❌✅✅✅✅
Dynamic Pricing (AI)❌❌❌❌❌✅
Multi-Currency❌❌❌❌❌✅
VAT/GST❌❌❌❌❌✅

Dependencies​

Upstream Dependencies (Required First)​

  • Identity & Tenancy (MVP.0) - Org/Account structure
  • Supply (MVP.0) - Spaces and Units
  • Authorization & Access (MVP.0) - Permission enforcement

Downstream Dependencies (Requires This Domain)​

  • Quotes, Holds & Bookings (V1.0) - Quote-to-booking workflow
  • Payments & Financials (V1.0) - Revenue split execution
  • Channels & Distribution (V1.0+) - Channel-specific pricing
  • Analytics & Audit (V1.0+) - Pricing history tracking

Migration Path​

From MVP.0/MVP.1 → V1.0​

Data Migration:

  1. Create default RatePlan for each existing Space
  2. Set base rates from external data source
  3. Map Spaces to tax jurisdictions
  4. Configure default revenue splits
  5. Seed TaxJurisdiction catalog (US only)

Feature Migration:

  • Replace hardcoded pricing with database-driven quotes
  • Migrate any external booking data to use Quotes

Estimated Effort: 3-4 weeks

  • Schema deployment: 1 day
  • Data migration: 3 days
  • API implementation: 2 weeks
  • Testing and validation: 1 week

V1.0 → V1.1 (Avalara Integration)​

Integration Steps:

  1. Configure Avalara MyLodgeTax account
  2. Map TaxJurisdictions to Avalara IDs
  3. Implement API client
  4. Migration script for existing tax rules
  5. Parallel run validation period

Estimated Effort: 2-3 weeks

Document Status: Complete Total Lines: 450+ Coverage: MVP.0 through V3.0