In Orb, an invoice is a detailed statement that outlines the charges a customer owes for a specific billing period. Understanding how invoices are calculated will help you manage billing effectively and anticipate charges.

​
Basic Definitions

An invoice is composed of several key components:
  1. Line Items: Each line item represents a charge associated with a specific Price object.
  2. Adjustments: Modifications that can alter the invoice total or individual line items. Adjustments include:
    • Minimums: Ensures a minimum charge is applied.
    • Maximums: Caps the charge at a certain amount.
    • Amount Discounts: Subtracts a fixed amount from the subtotal.
    • Usage Discounts: Reduces the billable quantity.
    • Percentage Discounts: Reduces the subtotal by a percentage.
    Adjustments can be applied at the line item level or across multiple line items but must adhere to the following rules:
    • Applicable only to prices with a real-world currency.
    • Usage discounts apply only to quantities at the line item level.
    • Other adjustments can be applied at both the line item and multi-line item levels.
    • Adjustments must be applied to Prices with the same cadence (billing period), billing mode (in-arrears or in-advance), and currency.
    • Percentage discounts can span different cadences as they distribute proportionally.
  3. Taxes (Optional): Calculated per line item if tax is enabled.
  4. Balance Transaction (Optional): Derived from the customer’s invoicing balance and applied after tax calculations.

​
Important Invariants

  • Unique Price Association: Each line item is linked to a unique Price object, whether added manually or generated by the billing engine.
  • No Duplicate Prices: An invoice cannot contain multiple line items referencing the same Price.
  • Currency Consistency: All line items should be in a single real-world currency but can include multiple virtual currencies, each with a conversion rate to the real-world currency.
  • Adjustment Association: Each adjustment is tied to one or more Price objects.

​
Calculating the True Total for a Line Item

The final amount due (total_with_tax) on an invoice is calculated by summing the “true total” of each line item. Each line item is calculated independently, and no calculations are exclusive to the invoice level, except for applying the customer invoice balance after taxes.

​
Step-by-Step Calculation

  1. Determine Line Item Quantity
    • The quantity is based on either:
      • The latest fixed fee quantity.
      • The total usage during the service period.
    • Multiple Quantities: If a Price covers multiple units (e.g., compute units per region), the line item will include a list of quantities, one for each unit type.
  2. Apply the Pricing Function
    • Calculates the subtotal based on the quantity or quantities.
    • Outputs a monetary amount in the Price’s currency, which can be a real-world currency (e.g., USD) or a virtual currency (e.g., Database credits).
    • Virtual Currencies: Must have a specified conversion rate to the plan’s real-world currency.
    • At this point, conversion rates are not yet applied if applicable.
  3. Apply Line Item Level Adjustments Adjustments at the line item level are applied to the subtotal in the following order:
    • Usage Discounts: Reduces the billable quantity (e.g., 100 units off).
    • Amount Discounts: Subtracts a fixed amount (e.g., $100 off or 100 credits off).
    • Percentage Discounts: Reduces the subtotal by a percentage (e.g., 10% off).
    • Minimums: Ensures the adjusted subtotal doesn’t fall below a certain amount (e.g., at least $10).
    • Maximums: Caps the adjusted subtotal at a certain amount (e.g., at most $100).
    Note: Adjustments operate in the Price’s currency, which may be a virtual currency.
  4. Apply Multi-Price/Invoice Level Adjustments
    • Adjustments that span multiple Prices (e.g., at the Plan level) are applied next.
    • The order of adjustments remains the same as above.
    • Must be applied to Prices sharing the same currency.
If an adjustment is applied to an invoice through a subscription configuration (i.e. through an adjustment interval), the adjustment interval bounds determine whether the adjustment is applied to the invoice based on whether the invoice date falls into the adjustment interval.If the adjustment applies to in-arrears fees, then the adjustment interval is inclusive of its end bound. If the adjustment applies to in-advance fees, then the adjustment interval is inclusive of its start bound. In the case that it applies to both, the interval is [inclusive, inclusive].
  1. Apply Prepaid Credits
    • Prepaid “credit balance” is applied to the adjusted subtotal.
    • Applicable to in-arrears charges only (not in-advance charges).
    • Credits must match the currency of the prices they are applied to.
  2. Apply Overage Conversion
    • If using a virtual currency, apply the overage conversion rate to convert to a real-world currency.
    • Each price may have a different conversion rate, but all must convert to the same real-world currency.
    • After this step, the amount is in a real-world invoicable currency.
  3. Subtract Previously Invoiced Amounts
    • For threshold-based invoicing, subtract any amounts previously invoiced during the billing period to avoid double billing.
  4. Apply Line Item Tax
    • Taxes are calculated per line item using integrated tax providers like TaxJar or Avalara.
    • Taxes are added when the invoice is issued, not on draft invoices.
    • External Invoicing Providers: If syncing with providers like Stripe, Orb does not calculate tax; it must be added externally.

​
Frequently Asked Questions

​
How are adjustments that apply across multiple prices distributed?

  • Proportional Distribution: Adjustments (excluding minimums) are distributed based on each line item’s proportion of the total subtotal.
    • Example: A $12 discount applies to Price A and Price B. If Price A has a subtotal of $5 and Price B has a subtotal of $15: 
      // Calculating the discount distribution
totalSubtotal = 5 + 15; // $20
priceADiscount = (5 / 20) * 12; // $3
priceBDiscount = (15 / 20) * 12; // $9
      • Price A receives a $3 discount.
      • Price B receives a $9 discount.
  • Minimum Adjustments: Distributed evenly among applicable line items.
Fixed-fee only invoices and minimums: Minimum adjustments are not applied to invoices that contain only fixed fees. This rule prevents minimums from being applied to the first in-advance invoice for subscriptions that don’t have any in-arrears usage-based fees, but applies more broadly to any invoice consisting entirely of fixed fees, regardless of timing or subscription type.
  • This distribution method does not affect the total invoice amount due.

​
Why is my invoice below the set minimum amount?

  • Prepaid Credits Impact: Minimums are applied before prepaid credits. For instance, with a $300 minimum and $200 in prepaid credits: 
    // Calculating the final amount due
adjustedSubtotal = max(subtotal, 300); // Apply minimum
finalAmountDue = adjustedSubtotal - 200; // Subtract prepaid credits
    • The adjusted subtotal is set to $300.
    • Prepaid credits reduce the amount due to $100.
  • Proration: Minimums may be prorated based on the service period.

​
Can I always invoice a fixed amount regardless of the customer’s prepaid balance?

  • Not Possible: Applying minimums after prepaid credits would overcharge the customer. 
    // Incorrect calculation that overcharges
adjustedSubtotal = subtotal - 200; // Subtract prepaid credits first
finalAmountDue = max(adjustedSubtotal, 200); // Apply minimum
// This results in the customer paying $200 on top of the $200 prepaid credits used
  • Correct Approach: Orb applies minimums before credits to prevent overcharging.

​
Can I have an adjustment that applies only to overage charges?

  • No: Adjustments are always applied before prepaid credits, affecting the total amount before considering overage.

​
What’s the difference between invoice balance and prepaid credits?

  • Invoice Balance:
    • Acts like a “payment method” applied after taxes.
    • Used to apply a future amount to the next invoice.
  • Prepaid Credits:
    • Applied before taxes.
    • Function as a usage commitment.
    • Only applicable to in-arrears charges.
    • Typically have start and expiration dates.

​
When might Orb produce a negative invoice amount?

  • Negative Invoices: Can occur during certain fixed fee downgrades.
  • Credit Notes: Usually, credits from downgrades are applied as credit notes on the original invoice instead of creating a negative invoice.

​
How are prepaid credits in a currency distributed across prices in the same currency?

  • Stable Distribution: Credits are allocated consistently based on price IDs.
  • Calculation Impact: The specific distribution does not affect the overall invoice total.