This guide provides a complete reference for managing Pricing Models in your billing system. It’s a flexible set of rules that automatically calculates how much to charge a customer based on what they use.

🧾 Pricing Model Schema

Fields

Field Type Required Description
name string ✅ Human-readable name of the pricing model
id string ⛔️ Unique ID for the pricing model, user-defined or system-generated
type `'recurring' 'one-time'` ✅
charge_type `'standard' 'tiered' 'volume'
baseAmount number ⛔️ Optional base charge in the billing cycle
components CompositeComponent[] ✅ List of meter-based charge components, only one component is allowed if charge_type is not “composite” else exactly two components allowed
combination_operator `'AND' 'OR'` ✅ if charge_type=composite
or_strategy `'higher' 'lower'` ✅ if operator is OR
currency string ✅ Billing currency (e.g., USD, PKR)
additional [{ key, value, type, inclusive }] ⛔️ Extra charges (tax, markup etc.)

🧩 Composite Component Schema

A pricing model may include multiple components. Each maps to a billing meter:

Field Type Required Description
meter_id string ✅ Reference to billingMeters.id, unique per component
pricing_type string ✅ One of: 'standard', 'tiered', 'volume', 'percentage', unique per component
pricing_schema (standard) { amount: number } Conditional Required if pricing_type is standard
pricing_schema (tiered) [{ lowerLimit, upperLimit, pricePerUnit, flatFee }] Conditional Used when tiered pricing. Upper limit of last tier must be an Infinity
pricing_schema (volume) Same as tiered Conditional Same as tiered
pricing_schema (percentage) { percentage: number, flatFee?: number } Conditional For revenue share models

➕ Additional Charges Schema

Field Type Required Description
key string ✅ Unique, e.g., tax, service_fee
value number ✅ Amount or percentage
type `'fixed' 'percentage'` ✅
inclusive boolean ✅ Whether the charge is inclusive or added to total

⚠️ Validations Summary

📊 Charge Model Type Behavior

One-Time vs. Recurring Types