Tax Engine

Automated tax calculation for domestic and international routes. Independent of ATPCO Tax Box, applying GST/VAT based on Origin/Destination pairs.

Core Function

The Tax Engine calculates applicable taxes in real-time during offer generation:

┌─────────────────────────────────────────────────────────────────┐
│                      Tax Engine                                  │
│                                                                 │
│   Offer Request                                                 │
│   ├── Origin: CCS                                               │
│   ├── Destination: MAR                                          │
│   └── Base Price: $75                                           │
│                                                                 │
│         ↓                                                       │
│                                                                 │
│   ┌─────────────────────┐                                       │
│   │   Tax Rule Lookup   │                                       │
│   │                     │                                       │
│   │   O&D: CCS → MAR    │                                       │
│   │   Type: Domestic VE │                                       │
│   │   Rate: IVA 16%     │                                       │
│   └──────────┬──────────┘                                       │
│              │                                                  │
│              ▼                                                  │
│                                                                 │
│   Tax Calculation                                               │
│   ├── Base: $75.00                                              │
│   ├── IVA (16%): $12.00                                         │
│   └── Total: $87.00                                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Tax Rules by Route Type

Domestic (Venezuela)

International (Outbound)

International (Inbound)

Tax Calculation Flow

Pricing Engine
      ↓
Base Price Calculated
      ↓
┌──────────────────────────────────────┐
│         Tax Engine API               │
│                                      │
│  Input:                              │
│  ├── Origin (IATA code)              │
│  ├── Destination (IATA code)         │
│  ├── Base Amount                     │
│  ├── Currency                        │
│  ├── Passenger Type (ADT/CHD/INF)    │
│  └── Flight Date                     │
│                                      │
│  Process:                            │
│  1. Determine route type (DOM/INT)   │
│  2. Lookup applicable tax rules      │
│  3. Apply rate/fixed calculations    │
│  4. Handle exemptions (INF, etc.)    │
│                                      │
│  Output:                             │
│  ├── Taxes[] with codes & amounts    │
│  └── Total tax amount                │
│                                      │
└──────────────────────────────────────┘
      ↓
Priced Offer with Taxes

Data Model

Tax Rule Schema

model TaxRule {
  id              String    @id @default(uuid()) @db.Uuid
  taxCode         String    @db.VarChar(3)  // IVA, XT, YQ, etc.
  name            String
  description     String?

  // Route applicability
  originCountry   String?   @db.VarChar(2)  // null = all
  originAirport   String?   @db.VarChar(3)  // null = all in country
  destCountry     String?   @db.VarChar(2)
  destAirport     String?   @db.VarChar(3)
  routeType       RouteType // DOMESTIC, INTERNATIONAL, BOTH

  // Calculation
  calcType        TaxCalcType // PERCENTAGE, FIXED, PER_SEGMENT
  rate            Decimal?    @db.Decimal(5, 4)  // For percentage
  fixedAmount     Decimal?    @db.Decimal(10, 2) // For fixed
  currency        String?     @db.VarChar(3)     // For fixed amounts

  // Applicability
  passengerTypes  String[]    // ADT, CHD, INF - empty = all
  cabinClasses    String[]    // Y, J, F - empty = all

  // Validity
  effectiveFrom   DateTime
  effectiveTo     DateTime?
  isActive        Boolean     @default(true)

  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @updatedAt

  @@index([originCountry, destCountry])
  @@index([taxCode])
  @@index([isActive, effectiveFrom])
}

enum RouteType {
  DOMESTIC
  INTERNATIONAL
  BOTH
}

enum TaxCalcType {
  PERCENTAGE
  FIXED
  PER_SEGMENT
  PER_PASSENGER
}

Tax Result Schema

model TaxCalculation {
  id              String    @id @default(uuid()) @db.Uuid
  offerId         String    @db.Uuid
  segmentId       String?   @db.Uuid

  taxCode         String    @db.VarChar(3)
  taxName         String
  baseAmount      Decimal   @db.Decimal(10, 2)
  taxAmount       Decimal   @db.Decimal(10, 2)
  currency        String    @db.VarChar(3)

  ruleId          String    @db.Uuid  // Reference to TaxRule applied

  createdAt       DateTime  @default(now())

  @@index([offerId])
}

API Design

Calculate Taxes Endpoint

POST /api/taxes/calculate

Request:
{
  "segments": [
    {
      "origin": "CCS",
      "destination": "MAR",
      "departureDate": "2025-03-15",
      "cabinClass": "Y"
    }
  ],
  "passengers": [
    { "type": "ADT", "count": 2 },
    { "type": "CHD", "count": 1 }
  ],
  "baseFare": {
    "amount": 75.00,
    "currency": "USD"
  }
}

Response:
{
  "taxes": [
    {
      "code": "IVA",
      "name": "Value Added Tax",
      "amount": 12.00,
      "currency": "USD",
      "perPassenger": false
    },
    {
      "code": "TSA",
      "name": "Airport Security",
      "amount": 10.50,
      "currency": "USD",
      "perPassenger": true,
      "breakdown": "3 passengers × $3.50"
    }
  ],
  "totalTax": 22.50,
  "grandTotal": 97.50,
  "currency": "USD"
}

Integration Points

Performance Requirements

Research Topics

• Tax treaty handling for international routes
• Infant exemption rules by country
• Tax refund processing for cancellations
• Real-time rate updates from authorities
• Multi-currency tax handling
• Tax reporting requirements by jurisdiction

Legacy: ATPCO Tax Box

For interline ticketing or complex international routings, ATPCO Tax Box may be used as a fallback:

• Complex multi-segment international itineraries
• Codeshare with legacy carriers
• Historical data for audits

Note: Primary tax calculation uses our internal Tax Engine for direct bookings.