Invoice deferral

​

Overview

Invoice deferral allows you to consolidate mid-cycle pricing changes into your next regularly scheduled invoice, rather than issuing immediate invoices. This keeps your customers’ billing experience predictable and consolidated, even when you need to make price changes mid-period. Deferral is supported for mid-cycle changes to all in_arrears fees (usage fees, which are always in_arrears, as well as in_arrears fixed fees).

​

Key benefits

• Predictable billing cadence: Customers receive invoices on their expected schedule (e.g., monthly on the 1st)
• Consolidated charges: Multiple pricing changes in a period appear on a single invoice
• Clear service periods: Invoices show separate line items for old and new rates with their respective date ranges

​

Is invoice deferral right for you?

Use invoice deferral if:

• Your customers expect invoices on a regular, predictable schedule
• You need to make pricing changes mid-cycle but want to avoid surprising customers with extra invoices
• Customer experience and billing predictability are priorities
• You’re making customer-favorable changes (price decreases, added discounts)
• The delay in invoicing (until the next scheduled date) doesn’t impact your cash flow requirements

Skip invoice deferral if:

• You need immediate payment for usage already incurred
• You’re making price increases that customers should be billed for right away
• You have specific revenue recognition requirements that need immediate invoicing
• You require real-time revenue collection for mid-cycle changes

​

Quick start

By default, 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. While this ensures accurate, real-time billing, it can lead to customers receiving multiple invoices in a single billing period. Invoice deferral lets you consolidate these mid-cycle changes into your next regularly scheduled invoice instead. Here’s how it works in the most common scenario—a mid-cycle price change: Scenario: You have a customer on a monthly billing cycle (billing date: 1st of each month). On September 12th, you need to lower their API Calls price from $1.00/1K to $0.80/1K effective immediately.

​

Without invoice deferral

What happens:

1. Orb immediately issues an invoice on Sep 12 for usage from Sep 1-12 at the old price ($1.00/1K)
2. On Oct 1, Orb issues the regular invoice for usage from Sep 12-30 at the new price ($0.80/1K)

Result: Your customer receives 2 invoices in September (Sep 1 and Sep 12)

​

With invoice deferral

What happens:

1. When you make the price change on Sep 12, you choose to defer the invoice
2. No invoice is generated on Sep 12
3. On Oct 1, Orb issues the regular invoice with two line items:
   • Sep 1-12 at $1.00/1K (old price)
   • Sep 12-30 at $0.80/1K (new price)

Result: Your customer receives only their expected monthly invoices. The Oct 1 invoice clearly shows both pricing periods.

​

How to enable invoice deferral

You can enable invoice deferral at the following levels: Account level, during a migration, via subscription edits, or via price_intervals API. More detail on each below:

​

Account level

Enable deferral for all customers and subscriptions by default. This is the simplest approach if you want consistent behavior across your entire account. Once enabled at the this level, all deferrable invoices for your customers and their subscriptions will be automatically deferred.

​

Migrations

When migrating customers to a new plan version, you can choose whether to defer the migration’s invoice. Orb uses your account-level default, but you can override it for each migration. For immediate migrations: For migrations on a specific date:

​

Subscription Edits

When editing subscriptions, you can choose whether to defer invoicing for changes resulting from the edit. Orb uses your account-level default, but you can override it for each edit. Note that the override option is only available for actions that support deferral, such as changes to usage fees or in-arrears fixed fees. The override won’t appear for changes to in-advance fixed fees, as these are invoiced immediately and cannot be deferred.

​

API configuration

For granular, subscription-specific control, you can configure deferral at the individual price level using the price intervals API. When to use this: Use API-level configuration when you need different deferral behavior for specific subscriptions or prices, such as:

• Managing add-ons: Defer specific add-ons while keeping base plan pricing behavior unchanged
• Enterprise custom pricing: Apply different deferral policies for specific customers (e.g., enterprise contracts requiring deferred billing)
• API-driven workflows: Programmatically control invoice behavior when your system automatically manages pricing changes

When you add or edit price intervals, include the boolean parameter can_defer_billing to control whether that specific price change should defer or invoice immediately. This parameter works for both adding new prices and editing existing price intervals.