Adjustments are modifications that can alter invoice totals or individual line items to implement pricing strategies like discounts, minimums, and maximums. They provide flexible control over billing calculations and can be applied at different scopes within your pricing structure.
Orb supports several types of adjustments that can be applied to modify billing calculations:
Amount discounts subtract a fixed amount from the subtotal. For example, a $100 discount reduces the charge by exactly $100.
Percentage discounts reduce the subtotal by a percentage. For example, a 20% discount on a $500 charge results in a $400 final amount.
Usage discounts reduce the billable quantity before applying the pricing function. For example, “100 units off” reduces the billable quantity by 100 units before calculating the charge.
Minimums ensure that the adjusted subtotal doesn’t fall below a specified amount. For example, “at least $50” guarantees that the final charge will be no less than $50, regardless of usage or other discounts.
Maximums cap the adjusted subtotal at a specified amount. For example, “at most $1000” ensures that the final charge will not exceed $1000, even with high usage.
Adjustments enable a wide range of billing scenarios:
Adjustments can be created through several methods:
Adjustments can be configured directly on plans and will apply to all subscriptions using that plan. These are useful for standard pricing policies that should apply consistently across customers.
Individual adjustments can be added to specific subscriptions using the subscription price intervals API. This allows for customer-specific pricing without modifying the underlying plan. See modifying subscriptions for more details on how to add, remove, and change adjustments on subscriptions.
Coupons are a special way to create reusable adjustments that come with a redemption code and usage tracking. When a coupon is redeemed, Orb automatically creates the corresponding adjustment and adjustment interval, applying it to the subscription.
Coupons always create subscription-scoped adjustments, meaning they apply to all prices on the subscription by default. This means that any new prices added to the subscription (such as through plan changes or add-ons) will automatically be included in the coupon’s discount.
Key differences from direct adjustments:
Coupons are particularly useful for promotional campaigns, employee discounts, and self-serve signup flows where customers need to apply discounts themselves.
Redeeming coupons:
Coupons can be redeemed using the redemption_code
when:
Adjustment behavior during subscription changes:
All adjustments, including those created by coupons, behave differently during mid-cycle changes:
Example: Mid-cycle upgrade with adjustment
A user upgrades their seats with 5 days remaining in a 30-day billing cycle from 1 seat to 2 seats on a plan that costs $60 per month per seat. A prorated charge of $10 is added in a new invoice for the upgrade.
Amount Discount ($20):
Percentage Discount (50%):
Amount discounts don’t apply to upgrade invoices to prevent scenarios where the upgrade would be free or over-discounted.
Orb uses a modern filter-based system to target adjustments precisely. This system consolidates multiple targeting dimensions into a unified model that supports price-, item-, and subscription-level scopes.
Filter-based adjustment targeting is currently in beta and only available to select Orb accounts. If you’re interested in using this functionality, please reach out to Orb support.
Filters use the following format:
Subscription-scoped: Apply to all prices on a subscription by using an empty filters array or applies_to_all: true
.
Item-scoped: Target specific items using item_id
filters. This is useful for applying discounts to particular products or services.
Price-scoped: Target specific prices using price_id
filters. This provides granular control over which charges receive adjustments.
Price type-scoped: Target prices by type using price_type
filters with values like:
usage
: Any usage-based price attached to a billable metricfixed_in_advance
: Fixed prices that bill in advancefixed_in_arrears
: Fixed prices that bill in arrearsfixed
: Any fixed fee (in advance or arrears)in_arrears
: Both usage and fixed fees that bill in arrearsYou should use only one of applies_to_all
, applies_to_item_ids
, or applies_to_price_ids
in a single adjustment. Or, use filters
instead to express more complex targeting logic.
Subscription-level discount:
Item-scoped maximum:
Advanced filtering:
applies_to_price_ids
continues to work alongside the new systemAdjustments are applied through adjustment intervals, which define the time period during which an adjustment is active. You can:
Adjustment intervals determine whether adjustments apply to invoices based on the invoice date and the adjustment’s time bounds:
Backdated adjustments and invoice reissuance:
When you create adjustment intervals with start dates in the past, Orb will automatically reissue any affected invoices to ensure they reflect the correct pricing. This happens because Orb maintains consistency between subscription state and invoice state using its diff-based billing engine.
For example, if you add a 10% discount effective from the beginning of the current month and invoices have already been issued for that period, Orb will:
This automatic correction ensures that your billing records always accurately reflect your intended pricing policies, even when adjustments are applied retroactively.
Use the subscription price intervals API to:
When you perform plan version migrations, adjustments behave differently depending on how they were originally configured. Understanding this behavior is crucial for maintaining consistent pricing policies across plan changes.
Automatic remapping: Adjustments configured at the plan level automatically adapt to plan version changes. When a price is edited in a new plan version (creating a new price ID), Orb automatically remaps the adjustment to apply to the replacement price.
Example: If you have a plan-level 10% discount that applies to all prices, and you edit a usage-based price in a new plan version, the discount will automatically apply to the new price ID without any manual intervention.
No automatic remapping: Adjustments added directly to subscriptions using applies_to_price_ids
cannot be automatically remapped during migrations. Since these adjustments target specific price IDs, they become “orphaned” when those prices are replaced with new IDs.
Migration protection: To prevent unintended consequences, Orb will fail the migration for subscriptions that have ad-hoc adjustments targeting prices that are being modified. This ensures you don’t accidentally lose discount policies or create billing inconsistencies.
Manual intervention required: You’ll need to manually update these adjustments before or after the migration to target the new price IDs.
Filter-based adjustments provide superior durability during plan migrations because they express intent rather than targeting specific price IDs:
Subscription-scoped filters (applies_to_all: true
or empty filters
array):
Item-scoped filters (item_id
targeting):
Price type-scoped filters (price_type
targeting):
Example of filter durability:
This adjustment will continue to apply to all storage-related prices, regardless of plan version changes or new price IDs.
For advanced functionality to automatically apply existing adjustments to replacement prices during migrations, please reach out to Orb support for access to private preview features.
Adjustments are applied during invoice calculation in a specific order to ensure consistent and predictable results. The calculation process follows these steps:
For prices configured with custom currencies (virtual pricing units), adjustments are applied in the price’s original currency before any overage conversion takes place. This means:
Example: If you have a price in “Database credits” with a 10% discount and the customer uses 1000 credits:
When adjustments apply to multiple prices, they are distributed proportionally based on each line item’s share of the total subtotal, except for minimums which are distributed evenly.
For detailed information about how adjustments factor into invoice calculations, including examples and edge cases, see the Invoice calculations documentation.
Adjustments are modifications that can alter invoice totals or individual line items to implement pricing strategies like discounts, minimums, and maximums. They provide flexible control over billing calculations and can be applied at different scopes within your pricing structure.
Orb supports several types of adjustments that can be applied to modify billing calculations:
Amount discounts subtract a fixed amount from the subtotal. For example, a $100 discount reduces the charge by exactly $100.
Percentage discounts reduce the subtotal by a percentage. For example, a 20% discount on a $500 charge results in a $400 final amount.
Usage discounts reduce the billable quantity before applying the pricing function. For example, “100 units off” reduces the billable quantity by 100 units before calculating the charge.
Minimums ensure that the adjusted subtotal doesn’t fall below a specified amount. For example, “at least $50” guarantees that the final charge will be no less than $50, regardless of usage or other discounts.
Maximums cap the adjusted subtotal at a specified amount. For example, “at most $1000” ensures that the final charge will not exceed $1000, even with high usage.
Adjustments enable a wide range of billing scenarios:
Adjustments can be created through several methods:
Adjustments can be configured directly on plans and will apply to all subscriptions using that plan. These are useful for standard pricing policies that should apply consistently across customers.
Individual adjustments can be added to specific subscriptions using the subscription price intervals API. This allows for customer-specific pricing without modifying the underlying plan. See modifying subscriptions for more details on how to add, remove, and change adjustments on subscriptions.
Coupons are a special way to create reusable adjustments that come with a redemption code and usage tracking. When a coupon is redeemed, Orb automatically creates the corresponding adjustment and adjustment interval, applying it to the subscription.
Coupons always create subscription-scoped adjustments, meaning they apply to all prices on the subscription by default. This means that any new prices added to the subscription (such as through plan changes or add-ons) will automatically be included in the coupon’s discount.
Key differences from direct adjustments:
Coupons are particularly useful for promotional campaigns, employee discounts, and self-serve signup flows where customers need to apply discounts themselves.
Redeeming coupons:
Coupons can be redeemed using the redemption_code
when:
Adjustment behavior during subscription changes:
All adjustments, including those created by coupons, behave differently during mid-cycle changes:
Example: Mid-cycle upgrade with adjustment
A user upgrades their seats with 5 days remaining in a 30-day billing cycle from 1 seat to 2 seats on a plan that costs $60 per month per seat. A prorated charge of $10 is added in a new invoice for the upgrade.
Amount Discount ($20):
Percentage Discount (50%):
Amount discounts don’t apply to upgrade invoices to prevent scenarios where the upgrade would be free or over-discounted.
Orb uses a modern filter-based system to target adjustments precisely. This system consolidates multiple targeting dimensions into a unified model that supports price-, item-, and subscription-level scopes.
Filter-based adjustment targeting is currently in beta and only available to select Orb accounts. If you’re interested in using this functionality, please reach out to Orb support.
Filters use the following format:
Subscription-scoped: Apply to all prices on a subscription by using an empty filters array or applies_to_all: true
.
Item-scoped: Target specific items using item_id
filters. This is useful for applying discounts to particular products or services.
Price-scoped: Target specific prices using price_id
filters. This provides granular control over which charges receive adjustments.
Price type-scoped: Target prices by type using price_type
filters with values like:
usage
: Any usage-based price attached to a billable metricfixed_in_advance
: Fixed prices that bill in advancefixed_in_arrears
: Fixed prices that bill in arrearsfixed
: Any fixed fee (in advance or arrears)in_arrears
: Both usage and fixed fees that bill in arrearsYou should use only one of applies_to_all
, applies_to_item_ids
, or applies_to_price_ids
in a single adjustment. Or, use filters
instead to express more complex targeting logic.
Subscription-level discount:
Item-scoped maximum:
Advanced filtering:
applies_to_price_ids
continues to work alongside the new systemAdjustments are applied through adjustment intervals, which define the time period during which an adjustment is active. You can:
Adjustment intervals determine whether adjustments apply to invoices based on the invoice date and the adjustment’s time bounds:
Backdated adjustments and invoice reissuance:
When you create adjustment intervals with start dates in the past, Orb will automatically reissue any affected invoices to ensure they reflect the correct pricing. This happens because Orb maintains consistency between subscription state and invoice state using its diff-based billing engine.
For example, if you add a 10% discount effective from the beginning of the current month and invoices have already been issued for that period, Orb will:
This automatic correction ensures that your billing records always accurately reflect your intended pricing policies, even when adjustments are applied retroactively.
Use the subscription price intervals API to:
When you perform plan version migrations, adjustments behave differently depending on how they were originally configured. Understanding this behavior is crucial for maintaining consistent pricing policies across plan changes.
Automatic remapping: Adjustments configured at the plan level automatically adapt to plan version changes. When a price is edited in a new plan version (creating a new price ID), Orb automatically remaps the adjustment to apply to the replacement price.
Example: If you have a plan-level 10% discount that applies to all prices, and you edit a usage-based price in a new plan version, the discount will automatically apply to the new price ID without any manual intervention.
No automatic remapping: Adjustments added directly to subscriptions using applies_to_price_ids
cannot be automatically remapped during migrations. Since these adjustments target specific price IDs, they become “orphaned” when those prices are replaced with new IDs.
Migration protection: To prevent unintended consequences, Orb will fail the migration for subscriptions that have ad-hoc adjustments targeting prices that are being modified. This ensures you don’t accidentally lose discount policies or create billing inconsistencies.
Manual intervention required: You’ll need to manually update these adjustments before or after the migration to target the new price IDs.
Filter-based adjustments provide superior durability during plan migrations because they express intent rather than targeting specific price IDs:
Subscription-scoped filters (applies_to_all: true
or empty filters
array):
Item-scoped filters (item_id
targeting):
Price type-scoped filters (price_type
targeting):
Example of filter durability:
This adjustment will continue to apply to all storage-related prices, regardless of plan version changes or new price IDs.
For advanced functionality to automatically apply existing adjustments to replacement prices during migrations, please reach out to Orb support for access to private preview features.
Adjustments are applied during invoice calculation in a specific order to ensure consistent and predictable results. The calculation process follows these steps:
For prices configured with custom currencies (virtual pricing units), adjustments are applied in the price’s original currency before any overage conversion takes place. This means:
Example: If you have a price in “Database credits” with a 10% discount and the customer uses 1000 credits:
When adjustments apply to multiple prices, they are distributed proportionally based on each line item’s share of the total subtotal, except for minimums which are distributed evenly.
For detailed information about how adjustments factor into invoice calculations, including examples and edge cases, see the Invoice calculations documentation.