Skip to main content

Platform Fees & Markup Rules

Kloyst charges a platform fee on top of Meta's base message costs. This document details the platform fee engine, rule types, and custom enterprise overrides.

🛠️ Platform Fee Rule Schema​

Platform fees are managed via the PlatformFeeRule database model:

model PlatformFeeRule {
  id            String   @id @default(uuid()) @db.Uuid
  name          String   @db.VarChar(255)
  feeType       FeeType  @default(PERCENTAGE) // PERCENTAGE | FLAT | HYBRID
  percentageFee Decimal  @default(0.25) @db.Decimal(5, 4)
  flatFee       Decimal  @default(0) @db.Decimal(12, 4)
  isDefault     Boolean  @default(false)
  vendorId      String?  @db.Uuid
  isActive      Boolean  @default(true)
  effectiveFrom DateTime @default(now())
  effectiveTo   DateTime?
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
}

🏷️ Rule Types & Cost Calculations​

The platform fee calculation depends on the configured feeType:

1. Percentage Fee (PERCENTAGE)​

Adds a percentage-based markup to Meta's base costs.

  • Formula: platformFee = estimatedMetaCost * percentageFee
  • Example: A campaign with ₹10,000 base cost and a 0.2500 (25%) fee rule:
    • platformFee = ₹2,500
    • totalCost = ₹12,500

2. Flat Fee (FLAT)​

Adds a flat transaction fee regardless of the campaign volume.

  • Formula: platformFee = flatFee
  • Example: A campaign with ₹10,000 base cost and a flat fee rule of 100.00 (₹100):
    • platformFee = ₹100
    • totalCost = ₹10,100

3. Hybrid Fee (HYBRID)​

Combines percentage and flat fees.

  • Formula: platformFee = (estimatedMetaCost * percentageFee) + flatFee
  • Example: A campaign with ₹10,000 base cost, 0.1000 (10%) fee rule, and a flat fee of 50.00 (₹50):
    • platformFee = (₹10,000 * 0.10) + ₹50 = ₹1,050
    • totalCost = ₹11,050

🛡️ Overrides & Global Defaults​

Kloyst applies platform fee rules using a strict priority order:

  1. Vendor Custom Override:
    • Matches vendorId = :vendorId and isActive = true.
    • Used for custom enterprise pricing agreements.
  2. Global Default:
    • Matches vendorId IS NULL, isDefault = true, and isActive = true.
    • Applied to standard self-service SaaS accounts.
  3. Hardcoded Fallback:
    • If no database rules are found, the engine uses a hardcoded fallback of 25% markup and logs a system warning.