Update Subscription

put

https://{subdomain}.{domain}/v2/subscriptions/{uuid}

Request an update to a subscription that takes place immediately, at
term renewal or at the next bill date.

Updating Canceled Subscriptions

If you need to update a canceled subscription, you need to first reactivate the subscription and then do the update call. You can look for the canceled subscription state to know if you need to do the reactivate call first.

While changing a canceled subscription may reactivate the subscription in some cases, there are scenarios where it will not reactivate the subscription, so we do not recommend allowing changes on a canceled subscription.

If you do submit an at renewal change to a canceled subscription and do not reactivate the subscription, it will expire at the end of the subscription term.

TIMEFRAME

The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur immediately, the next time the subscription is billed, or when the subscription renews. Generally, if you're performing an upgrade, you will want the change to occur immediately (now) or the next time the subscription is billed (bill_date). If you're performing a downgrade, you'll want the change to happen when the subscription renews (term_end) or the next time the subscription is billed (bill_date) so the customer gets what they paid for in their current billing cycle or term. The renewal timeframe option is accepted as an alias for term_end.

The timeframe control only applies to changes to the subscription's products. All non-product changes are always applied immediately. These changes have the option of applying at term end or bill date: plan_code, quantity, unit_amount_in_cents, subscription_add_ons.

Updating Refunded Subscriptions

Without the Credit Invoices feature enabled, Recurly does not reconcile invoice payments with subscription requests. If a subscription has a refund in the current billing cycle, updates with a timeframe of now will always credit the customer as if the refund never existed. Updates with a timeframe of term_end will not have this problem. Learn more.

ADD-ONS

If you include the subscription_add_ons array in your request, the subscription's original add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change. If you do not include the subscription_add_ons array, your current add-ons will remain in the subscription.

COUPONS

You can redeem a coupon in a subscription update if the update has a timeframe of now and you change something else about the subscription that triggers an invoice, like the plan, quantity, or price.

The coupon must include the subscription's plan as an eligible charge.

You can redeem multiple coupons with this format:

<coupon_codes>
    <coupon_code>savemore</coupon_code>
    <coupon_code>holidayspecial</coupon_code>
</coupon_codes>

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

uuid

string

required

Subscription's unique identifier.

Body Params

plan_code

string

required

length ≤ 50

Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.

currency

string

required

length ≤ 3

3-letter ISO 4217 currency code.

account

object

required

quantity

integer

≥ 0

Defaults to 1

Optionally override the default quantity of 1.

unit_amount_in_cents

integer

0 to 10000000

Override the unit amount of the subscription plan by setting this value in cents. If not provided, the subscription will inherit the price from the subscription plan for the provided currency. Max 10000000.

total_billing_cycles

integer

≥ 0

The total number of billing cycles for the current subscription term.

renewal_billing_cycles

integer

≥ 0

The number of billing periods in the subscription's next term. Will default to the plan's total_billing_cycles unless specified.

revenue_schedule_type

string

enum

Optional field for setting a revenue schedule type. This will determine how revenue for the associated Subscription should be recognized. When creating a Subscription, available schedule types are never, evenly, at_range_start, or at_range_end. If no revenue_schedule_type is set, the Subscription will inherit the revenue_schedule_type from its Plan.

Allowed:

trial_ends_at

date-time

If set, overrides the default trial behavior for the subscription. This must be a date and time, preferably in UTC. If the date is in the past, the subscription will skip the trial.

imported_trial

boolean

Defaults to false

Indicates if the subscription is to be treated as an import for data analysis or a real trial. This value can only be changed on a trial subscription and is persisted for its lifetime.

starts_at

date-time

If set, the subscription will begin on this specified date. The subscription will apply the setup fee and trial period, unless the plan has no trial. Omit this field if the subscription should be started immediately.

next_bill_date

date-time

Indicates the subscription's next billing period start date. Subsequent billing period start dates will be offset from this date. The first invoice will be prorated appropriately so that the customer only pays for the portion of the first billing period for which the subscription applies. Useful for forcing a subscription to bill on the first of the month.

coupon_code

string

Optional coupon code to redeem on the account and discount the subscription. Please note, the subscription request will fail if the coupon is invalid.

terms_and_conditions

string

Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.

customer_notes

string

Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.

bulk

boolean

Defaults to false

Optional field to be used only when needing to bypass the 60 second limit on creating subscriptions. Should only be used when creating subscriptions in bulk from the API. Set to true or false. Defaults to false.

transaction_type

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:

subscription_add_ons

array of objects

Defaults to []

Nested add-on information for the subscription. When creating, the new subscription will have no add-ons unless specified.

subscription_add_ons

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

proration_settings

object

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

gift_card

object

The gift card object is required in order to redeem a redemption code.

po_number

string

Optional notes field. Attach a PO number to the invoice.

net_terms

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.

net_terms_type

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:

collection_method

string

enum

Defaults to automatic

Optional field to set the collection for an invoice as automatic or manual. The default is automatic if it's not set.

Allowed:

Response

200