Invoice deferral scenarios

​

Overview

This reference guide covers all invoice deferral scenarios, from common cases to rare edge cases. Most users will only need to understand the basic scenarios covered in the main invoice deferral guide. Setup for all examples:

• Monthly cadence, Billing Cycle Date (BCD) = 1st
• Today: Sep 12
• Last scheduled billing date: Sep 1
• Next scheduled billing date: Oct 1
• Usage price: “API Calls”

General deferral rule: When a mid-cycle price change would normally create an immediate invoice, Orb defers the affected usage-based price(s) (also called in-arrears prices) to the next regularly scheduled invoice. When you choose to defer, Orb will add deferred charges to your next scheduled invoice on the customer’s normal billing cadence.

​

Common scenarios

​

Edge cases

The following scenarios cover edge cases that most users won’t encounter. These are provided as a reference for specific situations.

​

Things to avoid

While invoice deferral works seamlessly for most pricing changes, there are certain scenarios where mid-cycle changes can lead to unexpected results. This section covers situations to be cautious about when using deferral.

​

Tiered pricing (avoid mid-cycle)

Tiered charges depend on your cumulative usage within a billing period. Changing the price or tiers mid-cycle effectively “restarts” the count for the new segment, which can lead to unexpected totals (e.g., usage that should be billed at higher tiers may be re-evaluated from zero after the change). This makes invoices harder to predict and can over/under-charge relative to your intent. Guidance: If you need to change tier definitions or rates, schedule the change for the start of the next billing period so usage accrues cleanly under one set of tiers.

​

Adjustments (avoid mid-cycle)

Most mid-cycle adjustment changes are not recommended because they can lead to unexpected results. What doesn’t work well:

• Minimums/maximums: Changing minimums or maximums mid-cycle can create multiple thresholds in one period and lead to higher charges than expected. For example, raising a minimum from $10 to $20 halfway through the month could result in $30 total for that month ($10 for the first half + $20 for the second). Proration reduces this somewhat but doesn’t eliminate the issue entirely. If your goal was just to move to a $20 minimum going forward, this result may be unexpected.
• Discount-only changes: Changing only the adjustments (e.g., discounts) mid-period causes the new adjustment to apply retroactively to the entire current period even if you set the discount to be “effective immediately”.

What does work:

• Price AND discount together: Changing both price and discount mid-cycle works correctly. Each value applies for the time it was active: the old price and discount for the earlier part of the period, and the new price and discount for the later part. On the next invoice, both appear separately so charges match the timing of each change.

Guidance: To ensure clear, predictable billing, schedule all minimum, maximum, and discount-only changes for the start of the billing period. If you need to change both price and discount mid-cycle, that scenario is supported.

​

Invoice display

The following examples show how deferral appears on customer invoices. When invoice deferral is enabled, Orb separates old and new pricing periods into distinct line items, clearly indicating which rates or discounts apply to each portion of the billing cycle. Setup for the invoice display examples below: Note: The examples above use Sep dates, while the invoice display examples below use Oct dates, but follow the same behavior.

• Monthly cadence, BCD = 1st
• Today: Oct 21
• Last scheduled billing date: Oct 1
• Next scheduled billing date: Nov 1

​

Multiple line items

With deferral enabled, your next scheduled invoice may include multiple line items with the same price, each covering a different service period. For example, in the Nov 1 invoice shown below, you see: API Calls at old price (Oct 1-20), API Calls at new price (Oct 21-31).

​

Discount changes

When both price and discount change mid-cycle, the invoice displays two separate line items for that period: one for the old rate and discount, and another for the new rate and discount. Each line item corresponds to the distinct service period it covers. For example, in the invoice shown below, you see: API Calls billed at old price of $1.00 with a 10% discount (Oct 1-20), API Calls billed at new price with a 15% discount (Oct 21-31).