Invoice deferral

​

Current Orb invoicing behavior

When you make pricing changes mid-cycle in Orb, such as adjusting a rate, adding a new price, or updating discount terms, Orb immediately issues invoices to reflect the changes.

​

Example

• Last invoice: Sep 1
• Next scheduled invoice: Oct 1
• Today: Sep 12
• You lower a usage price (“API Calls”) effective today, Sep 12

Under current behavior, Orb will immediately issue a mid-cycle invoice on Sep 12 for usage from Sep 1 - Sep 12 at the old price, and on the Oct 1 invoice, include usage from Sep 12 - Sep 30 at the new price.

​

Invoice deferral feature

While immediate invoice issuance ensures accurate, real-time billing and faster collections, it can lead to customers receiving multiple invoices in a single billing period. Your customers might expect predictable invoices on a regular schedule from their vendor (for example a monthly recurring invoice). Invoice deferral lets you keep that schedule even when you make price changes mid billing period. Note that for the early access launch, deferral is available for usage-based fees only.

​

Core Behavior

General deferral rule: When a mid-cycle price change would normally create an immediate invoice, defer the affected usage-based price(s) 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. Below are examples of how Orb applies this rule, starting with a “happy path” scenario, followed by more complex cases that illustrate different conditions and variations. Setup for all examples (unless otherwise noted in the body of the example):

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

Scenario & Orb behavior	Example
#1. Mid-Cycle Price Change (“happy path scenario”) 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. -> 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 and Sep 12 - 30 at $0.80/1K.
#2: 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. -> Since your change is effective on cadence, deferral is a no-op and behavior would not change from normal. -> 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).
#3: 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, we bill at the earliest scheduled billing date for the deferred charge. If no regular invoice occurs by then, we issue a one-time invoice on that date. In short: we don’t hold monthly items for a quarterly invoice; we bill 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. -> 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 and Sep 12 - 30 at $2.00/1K calls. -> The Nov 1 invoice includes the platform fee and the API usage fee from Oct 1st - 31st 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. -> 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.
#5: 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. 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. - -> 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 and 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. -> 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) and 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.
#6: Quantity change-only invoices aren’t “scheduled billing dates” 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. -> 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- Sep 12 at $1.00/1K calls and 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. - -> 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. - -> 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- Sep 12 at $1.00/1K calls and 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).
#7: 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. -> 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).
#8. 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. -> 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 $80c/1K calls, you also increase the discount for API Calls from 10% to 15% effective immediately and choose to defer the invoice. -> 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.80c price.

​

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 below invoice display examples: Note: The examples under Core Behavior 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

1) Multiple line items for the same price: 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 below Nov 1 invoice, you see: API Calls at old price (Oct 1 - 20), API Calls at new price (Oct 21 - 31). 2) Two line items for a change in discount: 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 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).

​

Configuration

You can configure deferral both via UI and the API in the following surfaces: 1) Account level: this means that all deferrable invoices for all your customers and their subscriptions will be automatically deferred. 2) Plan Version Migration (“PVM”): Orb will use the default set at your Account level to determine deferral behavior. You can override this default and configure your deferral behavior at the time of each plan version migration for migrations that are immediate or on a specific date. (Note: Migrations that are Start of current term and Start of next term do not issue mid-cycle invoices.) Immediately On a specific date

3. API: You can also manage deferral behavior programmatically via the price_intervals endpoint.

• The price intervals_api takes in a boolean flag can_defer_billing as a param for all in-arrears prices to be deferred;
• The EditPriceIntervalParams (edit) also takes the same flag can_defer_billing and defers that specific line item.

​

Mid-cycle changes to be cautious of and guidance

​

Avoid mid-cycle price changes with tiered pricing

Why: 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.

​

Avoid mid-cycle changes to adjustments (Discounts/Min/Max) with one exception (#3 below)

Most adjustments mid-cycle are not recommended because they can lead to unexpected results.

1. 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 remove it entirely. If your goal was just to move to a $20 minimum going forward, this can feel confusing.
2. Changing only the adjustments (e.g. discounts) mid period leads to the new adjustment applying retroactively to the entire current period even if you set the discount to be “effective immediately”.
3. Changing both price and discount mid-cycle applies each value 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 changes for the start of the billing period.

​

Out of scope for early access (coming next)

Invoice deferral/fixed-fee change If you want to not charge upfront, use in arrears fixed fee (under plan setup) Invoice deferral/fixed-fee quantity change (e.g., increasing a platform fee from 1 seat -> 2 seats) docs

• Immediate changes: Bill prorated charges right away for the remaining period. These changes are not deferred and generate an invoice immediately.
• Scheduled changes: Set quantity updates to take effect on a future date to avoid extra invoices during the current billing period.