v1

latestOpenAPI 3.1.02026-07-261444991.2 MB

Subscription

Schedule plan change

This endpoint can be used to change an existing subscription's plan. It returns the serialized updated subscription object.

The body parameter change_option determines when the plan change occurs. Orb supports three options:

end_of_subscription_term: changes the plan at the end of the existing plan's term.
- Issuing this plan change request for a monthly subscription will keep the existing plan active until the start of the subsequent month. Issuing this plan change request for a yearly subscription will keep the existing plan active for the full year. Charges incurred in the remaining period will be invoiced as normal.
- Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, so the plan will be changed on February 1st, and invoice will be issued on February 1st for the last month of the original plan.
immediate: changes the plan immediately.
- Subscriptions that have their plan changed with this option will move to the new plan immediately, and be invoiced immediately.
- This invoice will include any usage fees incurred in the billing period up to the change, along with any prorated recurring fees for the billing period, if applicable.
- Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, so the plan will be changed on January 15th, and an invoice will be issued for the partial month, from January 1 to January 15, on the original plan.
requested_date: changes the plan on the requested date (change_date).
- If no timezone is provided, the customer's timezone is used. The change_date body parameter is required if this option is chosen.
- Example: The plan is billed monthly on the 1st of the month, the request is made on January 15th, with a requested change_date of February 15th, so the plan will be changed on February 15th, and invoices will be issued on February 1st and February 15th.

Note that one of plan_id or external_plan_id is required in the request body for this operation.

Customize your customer's subscriptions

Prices and adjustments in a plan can be added, removed, or replaced on the subscription when you schedule the plan change. This is useful when a customer has prices that differ from the default prices for a specific plan.

<Note> This feature is only available for accounts that have migrated to Subscription Overrides Version 2. You can find your Subscription Overrides Version at the bottom of your [Plans page](https://app.withorb.com/plans) </Note>

Adding Prices

To add prices, provide a list of objects with the key add_prices. An object in the list must specify an existing add-on price with a price_id or external_price_id field, or create a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object.

If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the price should be added to.

An object in the list can specify an optional start_date and optional end_date. If start_date is unspecified, the start of the phase / plan change time will be used. If end_date is unspecified, it will finish at the end of the phase / have no end time.

An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price.

Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference this price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Removing Prices

To remove prices, provide a list of objects with the key remove_prices. An object in the list must specify a plan price with either a price_id or external_price_id field.

Replacing Prices

To replace prices, provide a list of objects with the key replace_prices. An object in the list must specify a plan price to replace with the replaces_price_id key, and it must specify a price to replace it with by either referencing an existing add-on price with a price_id or external_price_id field, or by creating a new add-on price by including an object with the key price, identical to what would be used in the request body for the create price endpoint. See the Price resource for the specification of different price model configurations possible in this object.

For fixed fees, an object in the list can supply a fixed_price_quantity instead of a price, price_id, or external_price_id field. This will update only the quantity for the price, similar to the Update price quantity endpoint.

The replacement price will have the same phase, if applicable, and the same start and end dates as the price it replaces.

An object in the list can specify an optional minimum_amount, maximum_amount, or discounts. This will create adjustments which apply only to this price.

Additionally, an object in the list can specify an optional reference_id. This ID can be used to reference the replacement price when adding an adjustment in the same API call. However the ID is transient and cannot be used to refer to the price in future API calls.

Adding adjustments

To add adjustments, provide a list of objects with the key add_adjustments. An object in the list must include an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint.

If the plan has phases, each object in the list must include a number with plan_phase_order key to indicate which phase the adjustment should be added to.

Removing adjustments

To remove adjustments, provide a list of objects with the key remove_adjustments. An object in the list must include a key, adjustment_id, with the ID of the adjustment to be removed.

Replacing adjustments

To replace adjustments, provide a list of objects with the key replace_adjustments. An object in the list must specify a plan adjustment to replace with the replaces_adjustment_id key, and it must specify an adjustment to replace it with by including an object with the key adjustment, identical to the adjustment object in the add/edit price intervals endpoint.

The replacement adjustment will have the same phase, if applicable, and the same start and end dates as the adjustment it replaces.

Price overrides (DEPRECATED)

<Note> Price overrides are being phased out in favor adding/removing/replacing prices. (See [Customize your customer's subscriptions](/api-reference/subscription/schedule-plan-change)) </Note>

Price overrides are used to update some or all prices in a plan for the specific subscription being created. This is useful when a new customer has negotiated a rate that is unique to the customer.

To override prices, provide a list of objects with the key price_overrides. The price object in the list of overrides is expected to contain the existing price id, the model_type and configuration. (See the Price resource for the specification of different price model configurations.) The numerical values can be updated, but the billable metric, cadence, type, and name of a price can not be overridden.

Maximums, and minimums

Price overrides are used to update some or all prices in the target plan. Minimums and maximums, much like price overrides, can be useful when a new customer has negotiated a new or different minimum or maximum spend cap than the default for the plan. The request format for maximums and minimums is the same as those in subscription creation.

Scheduling multiple plan changes

When scheduling multiple plan changes with the same date, the latest plan change on that day takes effect.

Prorations for in-advance fees

By default, Orb calculates the prorated difference in any fixed fees when making a plan change, adjusting the customer balance as needed. For details on this behavior, see Modifying subscriptions.

post/subscriptions/{subscription_id}/schedule_plan_change

Path parameters

subscription_idstring required

Request body

usage_customer_idsstring[] nullable

A list of customer IDs whose usage events will be aggregated and billed under this subscription. By default, a subscription only considers usage events associated with its attached customer's customer_id. When usage_customer_ids is provided, the subscription includes usage events from the specified customers only. Provided usage_customer_ids must be either the customer for this subscription itself, or any of that customer's children.

filterstring nullable

An additional filter to apply to usage queries. This filter must be expressed as a boolean computed property. If null, usage queries will not include any additional filter.

plan_idstring nullable

The plan that the given subscription should be switched to. Note that either this property or external_plan_id must be specified.

external_plan_idstring nullable

The external_plan_id of the plan that the given subscription should be switched to. Note that either this property or plan_id must be specified.

per_credit_overage_amountnumber nullable

credits_overage_ratenumber nullable

trial_duration_daysinteger nullable

The duration of the trial period in days. If not provided, this defaults to the value specified in the plan. If 0 is provided, the trial on the plan will be skipped.

net_termsinteger nullable

The net terms determines the difference between the invoice date and the issue date for the invoice. If you intend the invoice to be due on issue, set this to 0. If not provided, this defaults to the value specified in the plan.

auto_collectionboolean nullable

Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. If not specified, this defaults to the behavior configured for this customer.

auto_issuanceboolean nullable

Used to determine if invoices for this subscription will be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null is specified, this defaults to the behavior configured for this customer.

default_invoice_memostring nullable

Determines the default memo on this subscription's invoices. Note that if this is not provided, it is determined by the plan configuration.

coupon_redemption_codestring nullable

Redemption code to be used for this subscription. If the coupon cannot be found by its redemption code, or cannot be redeemed, an error response will be returned and the subscription creation or plan change will not be scheduled.

invoicing_thresholdstring nullable

When this subscription's accrued usage reaches this threshold, an invoice will be issued for the subscription. If not specified, invoices will only be issued at the end of the billing period.

initial_phase_orderinteger nullable

The phase of the plan to start with

change_option'requested_date' | 'end_of_subscription_term' | 'immediate' required

change_datestring date-time nullable

The date that the plan change should take effect. This parameter can only be passed if the change_option is requested_date. If a date with no time is passed, the plan change will happen at midnight in the customer's timezone.

align_billing_with_plan_change_dateboolean nullable

[DEPRECATED] Use billing_cycle_alignment instead. Reset billing periods to be aligned with the plan change's effective date.

billing_cycle_alignment'unchanged' | 'plan_change_date' | 'start_of_month' nullable

Reset billing periods to be aligned with the plan change's effective date or start of the month. Defaults to unchanged which keeps subscription's existing billing cycle alignment.

plan_version_numberinteger nullable

Specifies which version of the plan to change to. If null, the default version will be used.

Response

metadataobject required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

idstring required

namestring required

The name of the subscription.

start_datestring date-time required

The date Orb starts billing for this subscription.

end_datestring date-time nullable required

The date Orb stops billing for this subscription.

created_atstring date-time required

current_billing_period_start_datestring date-time nullable required

The start date of the current billing period. This is an inclusive timestamp; the instant returned is exactly the beginning of the billing period. Set to null if the subscription is not currently active.

current_billing_period_end_datestring date-time nullable required

The end of the current billing period. This is an exclusive timestamp, such that the instant returned is not part of the billing period. Set to null for subscriptions that are not currently active.

status'active' | 'ended' | 'upcoming' required

active_plan_phase_orderinteger nullable required

The current plan phase that is active, only if the subscription's plan has phases.

default_invoice_memostring nullable required

Determines the default memo on this subscriptions' invoices. Note that if this is not provided, it is determined by the plan configuration.

auto_collectionboolean nullable required

Determines whether issued invoices for this subscription will automatically be charged with the saved payment method on the due date. This property defaults to the plan's behavior. If null, defaults to the customer's setting.

auto_issuanceboolean nullable required

Determines whether invoices for this subscription will be automatically issued. This resolves the effective setting for the subscription: a subscription-level override if set, otherwise the customer-level setting, otherwise the account-level default.

net_termsinteger required

Determines the difference between the invoice issue date for subscription invoices as the date that they are due. A value of 0 here represents that the invoice is due on issue, whereas a value of 30 represents that the customer has a month to pay the invoice.

billing_cycle_dayinteger required

The day of the month on which the billing cycle is anchored. If the maximum number of days in a month is greater than this value, the last day of the month is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing period begins on the 30th.

invoicing_thresholdstring nullable required