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”
Common scenarios
| Scenario & Orb behavior | Example |
|---|---|
| Mid-cycle price change Changes made mid-cycle to a usage-based price are added to the next scheduled invoice. This keeps your customer’s billing experience predictable and consolidated, while still showing clear service periods for the old and new rates. | On Sep 12, you decrease the API Calls price from $1.00/1K calls to $0.80/1K calls effective immediately and choose to defer the invoice. Result: • No invoice is generated on Sep 12 • On the Oct 1 invoice, API Calls appear as two line items: - Sep 1-12 at $1.00/1K - Sep 12-30 at $0.80/1K |
| On-cadence changes Changes that take effect exactly on the customer’s billing-cycle boundary are on-cadence and don’t alter invoicing—the “defer mid-period invoices” setting doesn’t apply, and no deferred line items are created or merged. | On Sep 12, you decrease the API Calls price from $1.00/1K calls to $0.80/1K calls effective on Oct 1st and choose to defer the invoice. Result: • Since your change is effective on cadence, deferral is a no-op and behavior does not change • The Oct 1 invoice includes the Sep 1-30 usage at $1.00/1K calls (the old price) • The new usage price starts Oct 1 and the Nov 1 invoice includes Oct 1-31 usage at $0.80/1K (new price) |
Edge cases
The following scenarios cover edge cases that most users won’t encounter. These are provided as a reference for specific situations.| Scenario & Orb behavior | Example |
|---|---|
| Mixed cadences: earliest-date billing When a subscription includes different cadences (e.g., monthly usage and a quarterly platform fee), the next scheduled invoice for one charge might be later than the earliest date the deferred charge would normally bill. In these cases, Orb does not keep deferring to match the longer cadence—Orb bills at the earliest scheduled billing date for the deferred charge. If no regular invoice occurs by then, Orb issues a one-time invoice on that date. In short: Orb doesn’t hold monthly items for a quarterly invoice; Orb bills at the first appropriate date so charges aren’t delayed. | a) Price change mid-period with mixed cadences On Sep 12, you increase the monthly API Calls price from $1.00/1K calls to $2.00/1K calls effective immediately and choose to defer the invoice. The subscription also has a quarterly platform fee with a next regular invoice on Nov 1. Result: • Earliest-date billing applies: Orb does not wait for Nov 1, the price change keeps a monthly cadence and establishes an Oct 1 billing date • On the Oct 1 invoice, API Calls appear as two line items: - Sep 1-12 at $1.00/1K calls - Sep 12-30 at $2.00/1K calls • The Nov 1 invoice includes the platform fee and the API usage fee from Oct 1-31 at $2.00/1K b) Ending the final monthly price (no regular monthly invoice exists) On Sep 12, you end the API Calls price ($1.00/1K calls), which is the only remaining monthly usage price effective immediately and choose to defer the invoice. The only other regular invoice is quarterly on Nov 1. Result: • Orb does not wait for Nov 1 and issues a one-time invoice on Oct 1 for the deferred usage, with API Calls from Sep 1-12 at $1.00/1K • The Nov 1 invoice includes the quarterly fee that is supposed to be billed on Nov 1 |
| Backdating Backdating means setting a price change with an effective date in the past. If backdated changes fall inside the current billing period, Orb moves the resulting mid-period charges to your next scheduled invoice. No extra, out-of-cycle invoice is issued. If a backdated price change takes effect before the last scheduled billing date (i.e., in a previous billing period), Orb does not carry those charges forward to the next invoice. Instead, Orb re-issues the previously billed invoice to reflect the corrected rates for that past period. | a) Backdated inside the current period On Sep 12, you backdate a price decrease to API Calls from $1.00/1K calls to $0.80/1K calls effective Sep 5 and choose to defer the invoice. Result: • No invoice is generated on Sep 12 for this change • On the Oct 1 invoice, API Calls appear as two line items: - Sep 1-5 at $1.00/1K calls - Sep 5-30 at $0.80/1K calls b) Backdated into a previous period On Sep 12, you backdate a price decrease to API Calls from $1.00/1K calls to $0.80/1K calls effective Aug 20 and choose to defer the invoice. Result: • Orb will re-issue the Sep 1 invoice where API Calls appear as two line items: - Aug 1-20 at $1.00/1K calls (old rate) - Aug 20-31 at $0.80/1K calls (new rate) • On the Oct 1 invoice, a new rate of API Calls at $0.80/1K calls is reflected for the entire month of Sep |
| Quantity change-only invoices A mid-cycle fixed-fee edit (e.g., seat/rate/quantity change) can generate an immediate change-only invoice. That invoice is not a scheduled billing date for deferral. Deferred charges from a mid-period price change still bill on the next scheduled invoice (your normal cadence anchor). If no regular invoice occurs by that date, Orb issues a one-time invoice on that scheduled date. We do not attach deferred charges to ad-hoc, quantity change-only invoices. | a) Mid-cycle fixed fee quantity change and usage fee change, a regular monthly invoice exists On Sep 12, you backdate a price decrease to API Calls from $1.00/1K calls to $0.80/1K calls effective Sep 5 and choose to defer the invoice. You also increase the quantity of in-advance fixed fee seats effective Sep 20. Another monthly price ensures a regular Oct 1 invoice. Result: • The Sep 1 invoice is edited to include the cost for the old seat quantity from Sep 1-20 • Orb will issue a Sep 20 invoice, which includes the pro-ration for the new seat quantity from Sep 20-30 • On the Oct 1 invoice, API Calls appear as two line items: - Sep 1-12 at $1.00/1K calls - Sep 12-30 at $0.80/1K calls b) Mid-cycle fixed fee quantity change and usage fee change, no regular monthly invoice exists On Sep 12, you end the only remaining monthly usage price effective immediately and choose to defer the invoice. The only other regular invoice is quarterly on Nov 1. On Sep 20, you increase the seat quantity effective immediately. Result: • The Sep 1 invoice is edited to include the cost for the old seat quantity from Sep 1-20 • Orb will issue a Sep 20 invoice, which includes the pro-ration for the new seat quantity from Sep 20-30 • On Oct 1, Orb bills the deferred usage via a one-time invoice for the period of Sep 1-12 c) Mid-cycle fixed fee quantity change and usage fee change, with mixed cadences On Sep 12, you decrease the API Calls price from $1.00/1K calls to $0.80/1K calls effectively immediately and choose to defer the invoice. There is also a quarterly platform fee with the next regular invoice scheduled for Nov 1. On Sep 20, you increase seat quantity effective immediately. Result: • The Sep 1 invoice is edited to include the cost for the old seat quantity from Sep 1-20 • Orb will issue a Sep 20 invoice, which includes the pro-ration for the new seat quantity from Sep 20-30 • On the Oct 1 invoice, API Calls appear as two line items: - Sep 1-12 at $1.00/1K calls - Sep 12-30 at $0.80/1K calls Note: Orb does not attach the deferred usage to the Sep 20 change-only invoice or wait to include it in the Nov 1 quarterly invoice. Orb bills the deferred monthly usage separately on Oct 1, either as a regular monthly invoice (if another monthly item exists) or as a one-time invoice (if it doesn’t). |
| Changes to allocation amounts mid-cycle Changes to allocation amount mid-cycle will lead to a one-time invoice with no line items. Currently these cannot be deferred. | On Sep 12, you edit the allocation for a plan and increase it from $500 to $1000 effective immediately and choose to defer the invoice. Result: • On Sep 12, Orb will issue an invoice without any line items (this is because currently we don’t show allocations as line items on an invoice as they are $0 cost basis) |
| Adjustment (e.g., discount application) Changing only a discount mid-cycle doesn’t create a new invoice, the new discount applies to the entire current billing period, not just from the change date. To have it start later, set the effective date to the beginning of the next period. Changing both the price and discount mid-cycle updates each for the time they were active, the old price and discount apply up to the change date, and the new price and discount apply after. On the next invoice, both appear separately so charges reflect the timing of each change. | a) Discount-only change mid-cycle On Sep 12, you change the “API Calls” discount from 10% to 15% without changing anything else. Result: • No mid-cycle invoice is created • On the Oct 1 invoice, the 15% discount shows that it is applied to the entire Sep 1-30 period b) Price and discount change mid-cycle On Sep 12, you decrease the price for API Calls from $1.00/1K calls to $0.80/1K calls, you also increase the discount for API Calls from 10% to 15% effective immediately and choose to defer the invoice. Result: • The Oct 1 invoice shows two line items: - 10% discount for Sep 1-12 for the $1 price - 15% discount for Sep 12-30 for the $0.80 price |
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”.
- 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.
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).