This guide provides detailed worked examples showing how Orb calculates invoice amounts through each step of the calculation pipeline. These examples demonstrate the interplay between usage, pricing models, adjustments, and credits.
The calculation pipeline
Every line item on an invoice passes through these seven steps in order:
| Step | Name | Description |
|---|
| 1 | Quantity | Evaluate billable metrics |
| 2 | Subtotal | Apply pricing function (quantity × rate) |
| 3 | Adjustments | Apply in order: Usage discount → Amount discount → Percent discount → Minimum → Maximum |
| 4 | Prepurchase | Deduct prepaid credits |
| 5 | Conversion | Convert virtual to real currency |
| 6 | Partial | Subtract previously invoiced amounts |
| 7 | Tax | Calculate and add tax |
Example 1: Usage-based pricing with tiered rates
A SaaS company charges for API calls using tiered pricing:
| Tier | Range | Price per call |
|---|
| 1 | 0 - 10,000 | $0.001 |
| 2 | 10,001 - 100,000 | $0.0008 |
| 3 | 100,001+ | $0.0005 |
Step 1: Quantity
Total API calls = 150,000
Step 2: Subtotal (Tiered pricing)
Tier 1: 10,000 calls × $0.001 = $10.00
Tier 2: 90,000 calls × $0.0008 = $72.00
Tier 3: 50,000 calls × $0.0005 = $25.00
─────────────────────────────────────────
Subtotal = $107.00
Step 3: No adjustments applied
Step 4: No prepaid credits
Step 5: Already in USD (no conversion)
Step 6: No previous partial invoices
Step 7: Tax (8%)
$107.00 × 0.08 = $8.56
─────────────────────────────────────────
Total with tax = $115.56
Example 2: Multiple adjustments in order
A customer has a plan with:
- Usage-based compute pricing: $0.10 per compute hour
- 10% percentage discount
- $50 minimum charge
- $500 maximum charge
Customer usage: 200 compute hours
Step-by-step calculation:
Step 1: Quantity
Compute hours = 200
Step 2: Subtotal
200 hours × $0.10 = $20.00
Step 3: Adjustments (in order)
3a. Usage discount: None
Current: $20.00
3b. Amount discount: None
Current: $20.00
3c. Percent discount: 10%
$20.00 × 0.10 = $2.00 discount
Current: $20.00 - $2.00 = $18.00
3d. Minimum: $50
$18.00 < $50, apply minimum
Delta: $50.00 - $18.00 = +$32.00
Current: $18.00 + $32.00 = $50.00
3e. Maximum: $500
$50.00 < $500, no change
─────────────────────────────────────
After adjustments = $50.00
Step 4-7: No credits, conversion, or partial invoices
Tax (10%): $50.00 × 0.10 = $5.00
─────────────────────────────────────────
Total with tax = $55.00
The order of adjustments matters significantly. Percentage discounts are applied before minimums, which means a discount can reduce the subtotal below the minimum, and then the minimum kicks in. This is intentional—it ensures customers always pay at least the minimum commitment.
Example 3: Prepaid credits with minimum charges
A customer has:
- $500 prepaid credits
- Usage-based charges totaling $300
- $400 minimum commitment
The key insight: Minimums are applied before prepaid credits are deducted.
Step-by-step calculation:
Step 2: Subtotal
Usage charges = $300.00
Step 3: Adjustments
Minimum check: $300 < $400
Apply minimum delta = +$100.00
─────────────────────────────────────────
After minimum = $400.00
Step 4: Prepurchase (prepaid credits)
Available credits: $500
Amount to deduct: $400
Credits used = $400.00
─────────────────────────────────────────
After prepurchase = $0.00
Remaining credits = $100.00
Step 7: Tax (10%)
Tax on $0.00 = $0.00
─────────────────────────────────────────
Amount due = $0.00
Example 4: Multi-line item with invoice-level adjustments
A customer has two prices on their plan:
- Compute: $0.10/hour, 1,000 hours used = $100
- Storage: $0.05/GB, 500 GB used = $25
- Invoice-level discount: $20 off (applies to both)
How the discount is distributed:
Total subtotal: $100 + $25 = $125
Distribution formula:
Price A share = (Price A subtotal / Total subtotal) × Discount
Compute discount:
($100 / $125) × $20 = $16.00
Storage discount:
($25 / $125) × $20 = $4.00
Final line items:
Compute: $100.00 - $16.00 = $84.00
Storage: $25.00 - $4.00 = $21.00
─────────────────────────────────────────
Invoice subtotal = $105.00
Invoice-level adjustments are distributed proportionally based on each line item’s share of the total subtotal. This ensures the adjustment is fairly allocated across all applicable prices.
Example 5: Virtual currency with conversion
A customer uses “Compute Credits” (virtual currency) with:
- Conversion rate: 1 credit = $0.50 USD
- 1,000 credits prepaid
- 1,500 credits used this period
Step-by-step calculation:
Step 2: Subtotal (in virtual currency)
Usage: 1,500 credits
Step 4: Prepurchase
Available: 1,000 credits
Deducted: 1,000 credits
─────────────────────────────────────────
Overage: 500 credits
Step 5: Conversion (virtual to real currency)
500 credits × $0.50/credit = $250.00
─────────────────────────────────────────
After conversion = $250.00
Step 7: Tax (10%)
$250.00 × 0.10 = $25.00
─────────────────────────────────────────
Total with tax = $275.00
Example 6: Threshold billing (partial invoices)
Threshold billing issues an invoice when accumulated charges exceed a threshold. Here’s how subsequent invoices handle previously invoiced amounts.
Setup:
- Threshold: $500
- First invoice issued at $520 (charges accumulated to that point)
- End of period: total charges are $800
End-of-period invoice calculation:
Step 2: Subtotal
Total period charges = $800.00
Steps 3-5: Adjustments, credits, conversion
(Assuming none for simplicity) = $800.00
Step 6: Subtract previously invoiced
Threshold invoice total = $520.00
─────────────────────────────────────────
Remaining charges = $280.00
Step 7: Tax (10%)
$280.00 × 0.10 = $28.00
─────────────────────────────────────────
Total with tax = $308.00
Example 7: Complex scenario with all components
A customer has:
- Usage price: Tiered API calls ($0.01 for first 10K, $0.005 thereafter)
- Fixed fee: $100/month platform fee (in-arrears)
- Percent discount: 15% (invoice-level)
- Minimum: $200
- Prepaid credits: $150 USD
- Customer balance: $30 (from previous refund)
- Tax rate: 8%
Usage: 50,000 API calls
Step-by-step calculation:
Step 2: Subtotals
API calls (tiered):
10,000 × $0.01 = $100.00
40,000 × $0.005 = $200.00
API subtotal = $300.00
Platform fee (in-arrears) = $100.00
─────────────────────────────────────────
Total subtotal = $400.00
Step 3: Adjustments
3c. Percent discount (15%):
$400.00 × 0.15 = $60.00 discount
Distributed:
API: ($300/$400) × $60 = $45.00
Fee: ($100/$400) × $60 = $15.00
After discount = $340.00
3d. Minimum ($200):
$340.00 > $200, no change = $340.00
Step 4: Prepurchase
Available: $150.00
Eligible (in-arrears only):
API (in-arrears): $255.00
Fee (in-arrears): $85.00
Total eligible: $340.00
Credits applied = $150.00
─────────────────────────────────────────
After prepurchase = $190.00
Step 7: Tax (8%)
$190.00 × 0.08 = $15.20
─────────────────────────────────────────
Total with tax = $205.20
Step 8: Customer balance
Balance applied = $30.00
─────────────────────────────────────────
Amount due = $175.20
Adjustment sign conventions
When working with the API or debugging invoice calculations, understanding delta signs is important:
| Adjustment Type | Delta Sign | Effect |
|---|
| Usage discount | Negative | Reduces quantity, lowering subtotal |
| Amount discount | Negative | Directly reduces subtotal |
| Percent discount | Negative | Reduces subtotal by percentage |
| Minimum | Positive | Increases subtotal to meet floor |
| Maximum | Negative | Reduces subtotal to meet ceiling |
Debugging calculation discrepancies
If an invoice total doesn’t match expectations:
-
Check adjustment order: Adjustments apply in a specific sequence. A discount might reduce charges below a minimum, which then gets raised.
-
Verify prepaid credit eligibility: Only in-arrears charges are eligible for prepaid credit deduction. In-advance fixed fees are not.
-
Confirm currency matching: Prepaid credits must match the currency of the prices they’re applied to.
-
Review threshold billing: If using threshold billing, check if amounts were already invoiced on a partial invoice.
-
Inspect customer balance: Customer balance is applied after tax, which can cause confusion if you’re comparing pre-tax amounts.
Advanced calculation scenarios
This section covers how Orb handles specific edge cases to help you understand the expected behavior for complex billing configurations.
In-advance charges and prepaid credits
Prepaid credits apply only to in-arrears charges. If a price is configured to bill “in advance” (charged at the start of the period), it will not draw from prepaid credits. This applies regardless of whether it’s a fixed fee or usage-based charge—the billing timing determines credit eligibility, not the fee type.
This design ensures that prepaid credits reduce actual usage charges rather than upfront commitments, which aligns with how most businesses model usage-based prepayment.
Customer has: $1,000 prepaid credits
Charges:
In-advance platform fee: $200 (NOT eligible for credits)
In-arrears usage charges: $300 (eligible for credits)
─────────────────────────────────────────
Credits applied: $300 (to in-arrears only)
Remaining credits: $700
Amount due: $200 (in-advance fee)
How invoice-level minimums are distributed
When an invoice-level minimum is applied, the delta (the amount needed to reach the minimum) is distributed equally across all applicable line items. This equal distribution ensures consistent line-item attribution for reporting and revenue recognition.
Setup:
Invoice-level minimum: $100
Compute charges: $30
Storage charges: $30
Total charges: $60 (below minimum)
Calculation:
Delta to reach minimum: $100 - $60 = $40
Per line item: $40 ÷ 2 = $20 each
Result:
Compute: $30 + $20 = $50
Storage: $30 + $20 = $50
Total: $100 (meets minimum)
Proration of minimums and maximums
When a subscription starts or ends mid-cycle, minimums and maximums are prorated proportionally to the billing period served. A $100/month minimum on a 15-day proration becomes a $50 minimum. This ensures customers are only held to commitments proportional to their active period.
Setup:
Monthly minimum: $100
Subscription starts mid-month (15 of 30 days)
Calculation:
Prorated minimum: $100 × (15/30) = $50
Actual charges: $30
Result:
Minimum delta applied: $50 - $30 = $20
Final charge: $50 (prorated minimum)
Threshold billing and partial invoice reconciliation
When threshold billing creates multiple partial invoices within a billing period, Orb tracks the highest amount invoiced per price. The end-of-period invoice subtracts this highest amount, ensuring accurate reconciliation when usage is recalculated between threshold events.
Scenario:
Threshold: $500
Day 10: Usage hits $520, partial invoice issued
Day 15: Usage recalculated to $650, new partial invoice issued
Day 30: Final usage is $800
End-of-period calculation:
Total charges: $800
Subtract highest partial: $650 (not $520 + $650)
─────────────────────────────────────────
Remaining to invoice: $150
