We’ve introduced a new invoice deferral option that lets you consolidate changes to usage based prices and in_arrears fixed fees to the next scheduled invoice, avoiding multiple invoices within the same billing period.

What’s new

• Deferred billing for usage-based prices and in_arrears fixed fees (fixed fees that are charged at the end of the billing period): Mid-cycle price updates no longer trigger immediate invoices; you can now defer them to align with your customer’s normal billing cadence.
  
  
• Flexible configuration: Control deferral at the account level, during plan version migrations, via subscription edits, or via the API using the can_defer_billing flag.
  
  
• Accurate service breakdowns: Deferred invoices clearly show separate line items for old and new prices (and discounts, when applicable).
  
  

Why it matters

This change keeps invoices predictable and consolidated for customers while maintaining full accuracy and visibility into rate changes.

Availability

Invoice deferral is available in GA for all customers. 

Documentation

Learn more about configuration options and behavior examples in our docs.

We have introduced a new mark_as_paid field on the apply subscription changes API. This new field marks all payable invoices as finalized and paid, and works in tandem with the is_payable_now field that exists on changed resources (see: https://changelog.withorb.com/api-update-is_payable_now-field-added-to-changed_resources.created_invoices-3pIhZC).

The previously_collected_amount field is optional. If not provided, we assume the amount was correctly collected and simply mark invoices as paid without touching the customer balance.

When both mark_as_paid and previously_collected_amount are provided, we mark all payable invoices as paid and decrement customer balance by (previously_collected_amount - total amount due). This should only be used when the amount collected outside the system differs from the total amount due. Note that the total amount due includes tax calculations, while the amount shown for pending changes does not include taxes (see: https://docs.withorb.com/essentials/pending-changes for more info).

Any negative customer balance will be automatically reflected on the next invoice.

We’ve introduced a new field, is_payable_now, on changed_resources.created_invoices. The created_invoices field represents the list of invoices that will be generated as part of a pending subscription change or when previewing changes with the Include-Changed-Resources header. The new is_payable_now field on invoices represent ready-to-pay invoices containing only in-advance fixed fees. You can use this field to determine which invoices should be paid to enable access to a subscription change (eg. plan upgrade).

When it applies:

changed_resources (and thus created_invoices) are only returned

• When the explicit Include-Changed-Resources header is passed in a Subscription API request
• When calling the Pending Subscription Changes APIs

When adding a pre-purchase allocation to a plan or subscriptions, Orb now supports a custom expiration option for each allocation credit block. This option allows you to set a specific number of days or months after which the block should expire. This option can be configured in both our UI and API.

To learn more about allocations, please visit our docs.

Orb now has support for creating hierarchical relationships between your customers to power flexible pricing, usage aggregation, and invoicing.

This capability is particularly valuable when your customers desire to aggregate usage across multiple customers on a single parent invoice while maintaining the ability to configure pricing per customer or groups of customers.

Learn more about this new powerful capability in our product documentation

Subscription modification endpoints now support an optional boolean parameter: allow_invoice_credit_or_void.

    •    Defaults to True (maintains existing behavior).

    •    Set to False to prevent modifications that would create a credit note or void an invoice. Instead, such requests will fail with a validation error.

When to use this

Certain modifications, like canceling a subscription mid-period with an in-advance fixed fee, typically generate credit notes. If you’re confident your modifications shouldn’t create these, set allow_invoice_credit_or_void=False as a safeguard.

Equivalent to a Dry-Run

This functions similarly to sending a dry-run request and previewing changes first, which allows for more precise validation of side effects.

Supported Endpoints

 - Cancel subscription

- Add or edit price intervals

- Trigger phase

- Update price quantity

We are now showing plan phases in subscription timelines, allowing you to see when the given phase of a plan starts and ends.

When creating a new subscription or scheduling a plan change, you may now select a plan version to subscribe to. Previously, new subscriptions could only and plan changes could only target the default version.

This functionality is also available in the API, via the plan_version_number field in the create subscription endpoint, and the schedule plan change endpoint. If the field is null or absent, the default version will be used.

Orb's API now supports adding, removing, and replacing prices when creating a new subscription, or changing the plan for an existing subscription (See: Subscription Price Overrides). This is useful when a new customer has negotiated one or more different prices for a specific plan than the plan's default prices.

For information on how to use this feature, see the API specification:

• Create subscription API
• Schedule plan change API

You can now set a customer’s tax exemption status - tax exempt or not tax exempt directly from the Create Customer or the Update Customer API endpoints. This feature enables smoother integrations and more automated workflows for managing tax compliance. You could use this to: exclude tax collection for customers in specific countries, mark tax-exempt organizations like nonprofits or government entities as tax-exempt in Orb upon creation, or manage tax externally for a specific subset of customers.

More information about Orb's supported tax providers can be found here.