Skip to main content
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:

​
Example 1: Usage-based pricing with tiered rates

A SaaS company charges for API calls using tiered pricing: Customer usage: 150,000 API calls this month Step-by-step calculation:

​
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:
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:
Why this order? If prepaid credits were applied before the minimum, customers could avoid contractual minimums by maintaining a credit balance. By applying the minimum first, the commitment is enforced, and then credits reduce the actual payment.

​
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:
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:

​
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:

​
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:

​
Adjustment sign conventions

When working with the API or debugging invoice calculations, understanding delta signs is important:

​
Debugging calculation discrepancies

If an invoice total doesn’t match expectations:
  1. Check adjustment order: Adjustments apply in a specific sequence. A discount might reduce charges below a minimum, which then gets raised.
  2. Verify prepaid credit eligibility: Only in-arrears charges are eligible for prepaid credit deduction. In-advance fixed fees are not.
  3. Confirm currency matching: Prepaid credits must match the currency of the prices they’re applied to.
  4. Review threshold billing: If using threshold billing, check if amounts were already invoiced on a partial invoice.
  5. 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.

​
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.

​
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.

​
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.