Advanced Pricing Patterns

Billerang supports all modern pricing models for flexible monetization.

Pricing Models Overview

Model	Description	Use Case
Per Unit	Fixed price × quantity	Basic metered billing
Tiered	Different rates at thresholds	API calls (like OpenAI)
Volume	Rate applies to ALL units at threshold	Wholesale discounts
Package/Bundle	Included units + overage	Monthly plans
Matrix	Multi-dimensional pricing	Enterprise SaaS
Formula-based	Custom calculations	Negotiated rates
Counter-based	Aggregate over billing period	Monthly usage caps

Per Unit Pricing

Fixed price multiplied by quantity.

Configuration

{
  "pricePlanMatrix": {
    "code": "API_CALL_PRICING",
    "versions": [{
      "status": "PUBLISHED",
      "isMatrix": false,
      "price": 0.10
    }]
  }
}

Example: API calls at $0.10 each

• 100 calls = $10.00
• 1000 calls = $100.00

Tiered Pricing (OpenAI-Style)

Different rates at quantity thresholds. Each tier applies only to units within that tier.

Example: OpenAI Token Pricing

• First 1M tokens: $0.002/1K tokens
• 1M-10M tokens: $0.0015/1K tokens
• 10M+ tokens: $0.001/1K tokens

Configuration

{
  "pricePlanMatrix": {
    "code": "TOKEN_TIERED_PRICING",
    "versions": [{
      "status": "PUBLISHED",
      "isMatrix": true,
      "columns": [{
        "code": "QUANTITY_TIER",
        "type": "Range_Numeric"
      }],
      "lines": [
        { "priority": 1, "values": [{"from": 0, "to": 1000000}], "price": 0.002 },
        { "priority": 2, "values": [{"from": 1000001, "to": 10000000}], "price": 0.0015 },
        { "priority": 3, "values": [{"from": 10000001, "to": null}], "price": 0.001 }
      ]
    }]
  }
}

Calculation

For 15M tokens:

• First 1M: 1,000 × $0.002 = $2.00
• Next 9M: 9,000 × $0.0015 = $13.50
• Last 5M: 5,000 × $0.001 = $5.00
• Total: $20.50

Volume Pricing

Once threshold is reached, the rate applies to ALL units (not just incremental).

Configuration

{
  "pricePlanMatrix": {
    "code": "VOLUME_DISCOUNT",
    "versions": [{
      "isMatrix": true,
      "columns": [{ "code": "VOLUME_TIER", "type": "Range_Numeric" }],
      "lines": [
        { "priority": 1, "values": [{"from": 0, "to": 9999}], "price": 1.00 },
        { "priority": 2, "values": [{"from": 10000, "to": null}], "price": 0.80 }
      ]
    }]
  }
}

Comparison: Tiered vs Volume

For 15K units:

• Tiered: (10K × $1.00) + (5K × $0.80) = $14,000
• Volume: 15K × $0.80 = $12,000

Package/Bundle Pricing

Monthly plan with included units and overage pricing.

Configuration

1. Counter Template (Included Units)

{
  "counterTemplate": {
    "code": "MONTHLY_API_CALLS",
    "counterType": "CONSUMPTION",
    "ceiling": 100000,
    "calendar": "MONTHLY_BILLING_PERIOD"
  }
}

2. Recurring Charge (Base Fee)

{
  "recurringChargeTemplate": {
    "code": "MONTHLY_PLAN_FEE",
    "pricePlan": { "price": 99.00 }
  }
}

3. Usage Charge (Overage)

{
  "usageChargeTemplate": {
    "code": "API_OVERAGE",
    "linkedCounter": "MONTHLY_API_CALLS",
    "pricePlan": { "price": 0.05 }
  }
}

Flow

1. Each API call → decrement CounterPeriod.value
2. Counter hits 0 → subsequent calls create EDRs
3. EDRs rated at overage price ($0.05)
4. Month end → reset counter

Matrix Pricing

Multi-dimensional pricing based on multiple attributes.

Example: Region × CustomerType × Tier

{
  "pricePlanMatrix": {
    "code": "ENTERPRISE_MATRIX",
    "versions": [{
      "isMatrix": true,
      "columns": [
        { "code": "REGION", "type": "STRING" },
        { "code": "CUSTOMER_TYPE", "type": "STRING" },
        { "code": "PRODUCT_TIER", "type": "STRING" }
      ],
      "lines": [
        {
          "priority": 1,
          "ratingAccuracy": 3,
          "values": ["US", "Enterprise", "Pro"],
          "price": 500
        },
        {
          "priority": 2,
          "ratingAccuracy": 2,
          "values": ["EU", "Government", null],
          "price": 450
        },
        {
          "priority": 99,
          "ratingAccuracy": 0,
          "values": [null, null, null],
          "price": 600
        }
      ]
    }]
  }
}

Matching Logic

1. Find line with highest ratingAccuracy that matches
2. null values match anything (wildcards)
3. Default line (ratingAccuracy=0) is fallback

Formula-Based Pricing

EL Expression

PricePlanMatrix ppm = ...;
ppm.setAmountWithoutTaxEL("""
  #{
    basePrice = 100;
    customerDiscount = billingAccount.getCfValue('negotiated_discount') ?: 0;
    volumeBonus = quantity > 10000 ? 0.1 : 0;
    basePrice * (1 - customerDiscount - volumeBonus)
  }
""");

Script Instance

public class CustomPricingScript extends Script {
    @Override
    public void execute(Map<String, Object> context) {
        WalletOperation wo = (WalletOperation) context.get("walletOperation");
        ChargeInstance ci = (ChargeInstance) context.get("chargeInstance");

        String pricingModel = ci.getCfValue("BLRG__PricingModel");

        BigDecimal price;
        switch (pricingModel) {
            case "COST_PLUS_MARGIN":
                BigDecimal cost = fetchCost(wo);
                price = cost.multiply(new BigDecimal("1.25"));
                break;
            case "MARKET_RATE":
                price = fetchMarketRate(wo);
                break;
            default:
                price = wo.getUnitAmountWithoutTax();
        }

        context.put("unitPrice", price);
    }
}

BLRG__PricingModel Custom Field

Billerang extension for UI-driven pricing model selection.

Definition

{
  "customFieldTemplate": {
    "code": "BLRG__PricingModel",
    "appliesTo": "ChargeTemplate",
    "fieldType": "LIST",
    "listValues": [
      "PER_UNIT",
      "TIERED",
      "VOLUME",
      "PACKAGE",
      "MATRIX",
      "FORMULA",
      "COUNTER_BASED"
    ]
  }
}

UI Integration

When pricing model is selected, UI shows relevant configuration fields:

• PER_UNIT: Just price field
• TIERED: Tier configuration table
• PACKAGE: Counter selection + overage price
• MATRIX: Column definitions + line editor

Counter-Based Aggregation

Rating aggregated events over billing period.

Key Concept

CounterPeriod = Billing period context

Configuration

{
  "counterTemplate": {
    "code": "MONTHLY_API_USAGE",
    "counterType": "ACCUMULATOR",
    "calendar": "MONTHLY_CYCLE",
    "ceiling": null,
    "notificationLevels": [50, 80, 100]
  }
}

Flow

1. Each EDR increments CounterPeriod.value
2. At billing period end (via BillingRun):
   • Read total from CounterPeriod
   • Apply tiered/volume pricing to TOTAL
   • Create single WalletOperation
3. Counter reset for next period

Diagram

Complete OpenAI-Style Example

Product Configuration

OfferTemplate: OPENAI_DEVELOPER_PLAN
├── RecurringChargeTemplate: MONTHLY_BASE_FEE
│   └── PricePlan: $20/month
└── UsageChargeTemplate: TOKEN_USAGE
    ├── CounterTemplate: MONTHLY_TOKENS
    │   ├── counterType: CONSUMPTION
    │   └── ceiling: 1000000 (1M tokens included)
    └── PricePlanMatrix: TOKEN_OVERAGE_PRICING
        └── Lines (tiered):
            ├── 0-5M overage: $0.002/1K
            ├── 5M-20M overage: $0.0015/1K
            └── 20M+ overage: $0.001/1K

Monthly Flow

1. Day 1: RecurringCharge creates $20 WO
2. Daily: API calls decrement token counter
3. Counter exhausted: Subsequent calls create EDRs
4. Month end: Aggregate overage EDRs, apply tiered pricing
5. Generate invoice: Base fee + overage charges