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

🧩 Composite Component Schema

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

➕ Additional Charges Schema

⚠️ Validations Summary

• components[].pricing_type must match corresponding config
• combination_operator & or_strategy are required only if charge_type = composite
• All monetary values should be numbers, not strings
• At least one component is mandatory

📊 Charge Model Type Behavior

One-Time vs. Recurring Types

• One-Time: This is the most common. The customer is billed (e.g., monthly), and their usage counter resets to zero for the next month.
• Recurring: This is less common. The customer's usage carries over to the next billing period. This could be used for pre-paid credits that don't expire.

📊 Charge Model Behavior

This is the most important part. The system lets you pick from four main "billing methods" to charge for what a customer uses.

1. Standard Pricing (Simple Pay-As-You-Go)

This is the most basic model. You charge the same price for every single "unit" of use.

• Simple Example: You charge $0.05 per email sent. If a customer sends 1,000 emails, their bill is simply 1,000 x $0.05 = $50.

2. Tiered Pricing

This model is like a set of stairs. The price per unit "steps down" as the customer's usage goes up. Each "stair" is billed at its own rate.

• Simple Example:
• How it's Billed: If a customer sends 150 emails:
• Example with flat fee applied on each tier

3. Volume Pricing (Bulk Discount)

This model is different from Tiered. The total amount of use determines the single price for all units. It’s like a "buy in bulk" discount.

• Simple Example:
• How it's Billed: If a customer sends 150 emails:
• Example with flat fee on each tier

In this case, 25,000 API calls would cost 25,000 x $0.0006 + $10 = $25.

• Only one tier is selected based on total usage.
• Entire usage is billed at that tier’s rate.
• Optional flat fee.
• Example:

4. Percentage Pricing

This is perfect for charging a commission, like for a marketplace or payment processing.

• Simple Example: You run a platform and charge a 2.5% fee on every sale a user makes.
• How it's Billed: If a user sells 5,000 items:

⚙️ Composite Pricing

• Combines multiple components and meters.
• combination_operator: AND or OR
• or_strategy: required if OR is used — choose higher or lower cost.

🧠 Validations & Rules

• combination_operator and or_strategy are required for composite models.
• tiered, volume, and percentage must include correct pricing structure.
• Meter IDs in components must point to active billing meters.
• baseAmount is optional and will be added to the computed total.
• additional charges can be applied after meter-based total.

🧪 Sample Pricing Calculation Flow

1. Fetch pricingModel for the customer’s subscription.
2. Evaluate each component with usage data from meters.
3. For composite:
4. Apply any baseAmount and additional charges.
5. Return final billed amount.

🔄 Create Pricing Model

POST /public/v1/pricing/model

Body Example:

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

✏️ Update Pricing Model

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

• Only name field can be updated

❌ Delete Pricing Model

POST /public/v1/pricing/model/:pm_id

{
  "subscription": {
	  "next_action": "cancel" // "cancel" | "pause"
  }
}

• Any plans associated with the pricing model will be removed from usage-billing

📥 Get Pricing Model

GET /public/v1/pricing/model/:pm_id

• Fetch a single pricing model by ID

GET /public/v1/pricing/model/list

• Returns all pricing models for current account/store/mode

⚙️ Attach Pricing Model in Plan

When creating a usage-based plan, pass true in is_usage_based and attach pricing model id in the field pricing_model_id

POST /public/v1/plan

{
	...existingPayloadOfPlan,
  "is_usage_based": true,
  "pricing_model_id": "xpay_pm_id123...098"
}

This will create a plan with usage-based billing defined in the pricing model and then all of the subscriptions having that plan will be charged according to the defined pricing schema in pricing model.