HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
API Reference

Update a subscription

This only lets you change the subscription settings that have no impact on the billed amount. Use the Create Subscription Change endpoint to make those changes.

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
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
integer

The remaining billing cycles in the current term.

integer

If auto_renew=true, when a term completes, total_billing_cycles takes this value as the length of subsequent terms. Defaults to the plan's total_billing_cycles.

boolean
Defaults to true

Whether the subscription renews at the end of its term.

date-time

If present, this sets the date the subscription's next billing period will start (current_period_ends_at). This can be used to align the subscription’s billing to a specific day of the month. For a subscription in a trial period, this will change when the trial expires. This parameter is useful for postponement of a subscription to change its billing date without proration.

string
enum
Allowed:
string

Specify custom notes to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.

string

Specify custom notes to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.

string
length ≤ 50

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

string
length ≤ 50

The price segment ID, e.g. e28zov4fw0v2.

integer
≥ 0
Defaults to 0

Integer 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. For manual collection method, an additional 24 hours is
added to ensure the customer has the entire last day to make payment before
becoming past due. For example:

If an invoice is due net 0, it is due 'On Receipt' and will become past due 24 hours after it's created.
If an invoice is due net 30, it will become past due at 31 days exactly.
If an invoice is due eom 30, it will become past due 31 days from the last day of the current month.

For automatic collection method, the additional 24 hours is not added. For example, On-Receipt is due immediately, and net 30 will become due exactly 30 days from invoice generation, at which point Recurly will attempt collection.
When eom Net Terms Type is passed, the value for Net Terms is restricted to 0, 15, 30, 45, 60, or 90.

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:
credit_application_policy
object

Controls whether credit invoices are automatically applied to new invoices.
The mode field determines the application behavior. When mode is all,
the optional allowed_origins array can restrict which credit invoice origins
are applied.

string
length ≤ 13

If present, this subscription's transactions will use the payment gateway with this code.

boolean
Defaults to false
deprecated

This field is deprecated. Please do not use it.

shipping
object
string

The billing_info_id is the value that represents a specific billing info for an end customer. When billing_info_id is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. billing_info_id can ONLY be used for sites utilizing the Wallet feature.

string
length ≤ 255

Optionally overrides the suffix component of the composed transaction descriptor. If omitted, the suffix is derived from the subscription's plan name or the invoice description, with a Trial prefix on Visa trial conversions. Subject to gateway availability and payment method support.

Responses

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