This guide provides a complete reference for managing Pricing Models in your billing system. A Pricing Model defines how a subscription is charged using one or more meters and various pricing strategies.

🧾 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
`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
`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`
`pricing_type`	string	✅	One of: `'standard'`, `'tiered'`, `'volume'`, `'percentage'`
`standard`	`{ amount: number }`	Conditional	Required if pricing_type is `standard`
`tiered`	`[{ lowerLimit, upperLimit, pricePerUnit, flatFee }]`	Conditional	Used when `tiered` pricing
`volume`	Same as `tiered`	Conditional	For volume-based pricing
`percentage`	`{ percentage: number, flatFee?: number }`	Conditional	For revenue share models
`fixedPrice`	`number`	Optional	Flat charge per meter (independent of usage)

➕ Additional Charges Schema

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

🔄 Create Pricing Model

POST /public/v1/pricing/model

Body Example:

{
  "name": "Pro Plan",
  "id": "pro-plan-2025",
  "type": "recurring",
  "charge_type": "composite",
  "combination_operator": "OR",
  "or_strategy": "higher",
  "currency": "USD",
  "components": [
    {
      "meter_id": "api-requests",
      "pricing_type": "tiered",
      "tiered": [
        { "lowerLimit": 1, "upperLimit": 1000, "pricePerUnit": 0.01 },
        { "lowerLimit": 1001, "upperLimit": 10000, "pricePerUnit": 0.008 }
      ]
    },
    {
      "meter_id": "data-usage",
      "pricing_type": "percentage",
      "percentage": { "percentage": 2.5, "flatFee": 1 }
    }
  ],
  "additional": [
    { "key": "tax", "value": 10, "type": "percentage", "inclusive": false }
  ]
}

✏️ Update Pricing Model

PATCH /public/v1/pricing/model/:pm_id