HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
API Reference
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo

Create a new subscription change

post
https://v3.recurly.com/subscriptions//change

Calling this will overwrite an existing, pending subscription change.

If a subscription has a pending change, and a change is submitted which matches
the subscription as it currently exists, the pending change will be deleted,
and you will receive a 204 No Content response.

If a subscription has no pending
change, and a change is submitted which matches the subscription as it currently
exists, a 422 Unprocessable Entity validation error will be returned.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

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

Body Params
string
enum
Defaults to now

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.

Allowed:
string
length ≤ 13

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.

string
length ≤ 50

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.

string

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.

string

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.

string
length ≤ 50

The price segment ID, e.g. e28zov4fw0v2.

float
0 to 1000000

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

boolean
Defaults to false
deprecated

This field is deprecated. Please do not use it.

integer
≥ 0
Defaults to 1

Optionally override the default quantity of 1.

shipping
object

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.

coupon_codes
array of strings

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.

Coupon codes
add_ons
array of objects

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
Add-ons
string
enum
Defaults to automatic
Allowed:
string
enum
Allowed:
custom_fields
array of objects

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.

Custom fields
string
length ≤ 50

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

integer
≥ 0
Defaults to 0

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.

string
enum
Defaults to net

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.

Allowed:
string
enum

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.

Allowed:
billing_info
object

Accept nested attributes for three_d_secure_action_result_token_id

ramp_intervals
array of objects

The new set of ramp intervals for the subscription.

Ramp Intervals
proration_settings
object

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

date-time

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.

Responses

204

The previous pending change was reverted.

Updated 3 months ago

Did this page help you?
Language
Credentials
Basic
base64
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 3 months ago

Did this page help you?