Preview Subscription Change

Subscription ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`.

The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur now, when the subscription is next billed, or when the subscription term ends. Generally, if you're performing an upgrade, you will want the change to occur immediately (now). If you're performing a downgrade, you should set the timeframe to `term_end` or `bill_date` so the change takes effect at a scheduled billing date. The `renewal` timeframe option is accepted as an alias for `term_end`.

One ofbill_datenowrenewalterm_endDefault "now"

If you want to change to a new plan, you can provide the plan's code or id. If both are provided the `plan_id` will be used.

If you want to change to a new plan, you can provide the plan's code or id. If both are provided the `plan_id` will be used.

The `business_entity_id` is the value that represents a specific business entity for an end customer. When `business_entity_id` is used to assign a business entity to the subscription, all future billing events for the subscription will bill to the specified business entity. Available when the `Multiple Business Entities` feature is enabled. If both `business_entity_id` and `business_entity_code` are present, `business_entity_id` will be used. Only allowed if the `timeframe` is not `now`.

The `business_entity_code` is the value that represents a specific business entity for an end customer. When `business_entity_code` is used to assign a business entity to the subscription, all future billing events for the subscription will bill to the specified business entity. Available when the `Multiple Business Entities` feature is enabled. If both `business_entity_id` and `business_entity_code` are present, `business_entity_id` will be used. Only allowed if the `timeframe` is not `now`.

The price segment ID, e.g. `e28zov4fw0v2`.

Optionally, sets custom pricing for the subscription, overriding the plan's default unit amount. The subscription's current currency will be used.

This field is deprecated. Please do not use it.

Default false

Optionally override the default quantity of 1.

Default 1

Shipping addresses are tied to a customer's account. Each account can have up to 20 different shipping addresses, and if you have enabled multiple subscriptions per account, you can associate different shipping addresses to each subscription.

The id of the shipping method used to deliver the subscription. To remove shipping set this to `null` and the `amount=0`. If `method_id` and `method_code` are both present, `method_id` will be used.

The code of the shipping method used to deliver the subscription. To remove shipping set this to `null` and the `amount=0`. If `method_id` and `method_code` are both present, `method_id` will be used.

Assign a shipping address from the account's existing shipping addresses. If this and address are both present, address will take precedence.

A list of coupon_codes to be redeemed on the subscription during the change. Only allowed if timeframe is now and you change something about the subscription that creates an invoice.

If you provide a value for this field it will replace any existing add-ons. So, when adding or modifying an add-on, you need to include the existing subscription add-ons. Unchanged add-ons can be included just using the subscription add-on''s ID: `{"id": "abc123"}`. If this value is omitted your existing add-ons will be unaffected. To remove all existing add-ons, this value should be an empty array.' If a subscription add-on's `code` is supplied without the `id`, `{"code": "def456"}`, the subscription add-on attributes will be set to the current values of the plan add-on unless provided in the request. - If an `id` is passed, any attributes not passed in will pull from the existing subscription add-on - If a `code` is passed, any attributes not passed in will pull from the current values of the plan add-on - Attributes passed in as part of the request will override either of the above scenarios

When an id is provided, the existing subscription add-on attributes will persist unless overridden in the request.

If a code is provided without an id, the subscription add-on attributes will be set to the current value for those attributes on the plan add-on unless provided in the request. If `add_on_source` is set to `plan_add_on` or left blank, then plan's add-on `code` should be used. If `add_on_source` is set to `item`, then the `code` from the associated item should be used.

Used to determine where the associated add-on data is pulled from. If this value is set to `plan_add_on` or left blank, then add-on data will be pulled from the plan's add-ons. If the associated `plan` has `allow_any_item_on_subscriptions` set to `true` and this field is set to `item`, then the associated add-on data will be pulled from the site's item catalog.

One ofplan_add_onitemDefault "plan_add_on"

Allows up to 2 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount` cannot be provided.

Allows up to 9 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount_decimal` cannot be provided. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided.

If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount`. There must be one tier without an `ending_quantity` value which represents the final tier.

If percentage tiers are provided in the request, all existing percentage tiers on the Subscription Add-on will be removed and replaced by the percentage tiers in the request. Use only if add_on.tier_type is tiered or volume and add_on.usage_type is percentage. There must be one tier without an `ending_amount` value which represents the final tier. This feature is currently in development and requires approval and enablement, please contact support.

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage.

One ofat_range_endat_range_startevenlynever

One ofautomaticmanualDefault "automatic"

One ofat_range_endat_range_startevenlynever

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Fields must be created in the UI before values can be assigned to them.

Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.

The type of record a custom field was automatically copied from.

One ofaccountplanproductsubscription

The UUID of the record this custom field was automatically copied from. Only present when the field was copied from another record.

For manual invoicing, this identifies the PO number associated with the subscription.

Integer normally paired with `Net Terms Type` and representing the number of days past the current date (for `net` Net Terms Type) or days after the last day of the current month (for `eom` Net Terms Type) that the invoice will become past due. During a subscription change, it's not necessary to provide both the `Net Terms Type` and `Net Terms` parameters. For more information on how net terms work with `manual` collection visit our docs page (https://docs.recurly.com/docs/manual-payments#section-collection-terms) or visit (https://docs.recurly.com/docs/automatic-invoicing-terms#section-collection-terms) for information about net terms using `automatic` collection.

Default 0

Optionally supplied string that may be either `net` or `eom` (end-of-month). When `net`, an invoice becomes past due the specified number of `Net Terms` days from the current date. When `eom` an invoice becomes past due the specified number of `Net Terms` days from the last day of the current month.

One ofneteomDefault "net"

An optional type designation for the payment gateway transaction created by this request. Supports 'moto' value, which is the acronym for mail order and telephone transactions.

One ofmoto

The new set of ramp intervals for the subscription.

Represents the billing cycle where a ramp interval starts.

Default 1

Represents the price for the ramp interval.

Allows you to control how any resulting charges and credits will be calculated and prorated.

Determines how the amount charged is determined for this change

One offull_amountprorated_amountnoneDefault "prorated_amount"

Determines how the amount credited is determined for this change

One offull_amountprorated_amountnoneDefault "prorated_amount"

If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). When combined with proration_settings, proration calculation should occur, only supported when timeframe is now.

The ID of the Subscription Change.

The ID of the subscription that is going to be changed.

Just the important parts.

Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.

This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.

These add-ons will be used when the subscription renews.

Just the important parts.

Used to determine where the associated add-on data is pulled from. If this value is set to `plan_add_on` or left blank, then add-on data will be pulled from the plan's add-ons. If the associated `plan` has `allow_any_item_on_subscriptions` set to `true` and this field is set to `item`, then the associated add-on data will be pulled from the site's item catalog.

One ofplan_add_onitemDefault "plan_add_on"

Supports up to 2 decimal places.

Supports up to 9 decimal places.

One ofat_range_endat_range_startevenlynever

The pricing model for the add-on. For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.

One offlattieredstairstepvolumeDefault "flat"

The type of calculation to be employed for an add-on. Cumulative billing will sum all usage records created in the current billing cycle. Last-in-period billing will apply only the most recent usage record in the billing period. If no value is specified, cumulative billing will be used.

One ofcumulativelast_in_period

The time at which usage totals are reset for billing purposes.

One ofbilling_periodsubscription_termDefault "billing_period"

If tiers are provided in the request, all existing tiers on the Subscription Add-on will be removed and replaced by the tiers in the request. If add_on.tier_type is tiered or volume and add_on.usage_type is percentage use percentage_tiers instead. There must be one tier without an `ending_quantity` value which represents the final tier.

If percentage tiers are provided in the request, all existing percentage tiers on the Subscription Add-on will be removed and replaced by the percentage tiers in the request. Use only if add_on.tier_type is tiered or volume and add_on.usage_type is percentage. There must be one tier without an `ending_amount` value which represents the final tier. This feature is currently in development and requires approval and enablement, please contact support.

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage.

This field is deprecated. Please do not use it.

Default false

Returns `true` if the subscription change is activated.

One ofat_range_endat_range_startevenlynever

Verification transactions (used for free trial payment method validation)

Business entity details

The entity code of the business entity.

This name describes your business entity and will appear on the invoice.

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Fields must be created in the UI before values can be assigned to them.

Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.

The type of record a custom field was automatically copied from.

One ofaccountplanproductsubscription

The UUID of the record this custom field was automatically copied from. Only present when the field was copied from another record.

Accept nested attributes for three_d_secure_action_result_token_id

A token generated by Recurly.js after completing a 3-D Secure device fingerprinting or authentication challenge.

The ramp intervals representing the pricing schedule for the subscription.

Represents the billing cycle where a ramp interval starts.

Represents how many billing cycles are left in a ramp interval.

Represents the price for the ramp interval.

If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). When combined with proration_settings, proration calculation should occur, only supported when timeframe is now.