Note:
- This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.
- When the Remove mandatory add-ons from old plan during subscription plan update setting is enabled on your Chargebee site, all mandatory addons with the old plan will be automatically removed during the subscription update to a new plan.
You can modify the plan, plan quantity and add or remove addons for the subscription. By default the changes are applied immediately and the charges (/credits) are prorated and adjusted with the next billing term. You may also choose to effect the changes at the end of the current term by passing end_of_term as "true". In this case proration will not be done.
Only the parameters that are passed are modified for the subscription. Rest will reflect the existing values.
By default, the addons passed are appended to the existing list of addons for this subscription. In case a passed addon already exists for this subscription, quantity value is replaced. If you want to completely replace the addons for this subscription, pass replace_addon_list as "true".
Card and 'vat_number' attributes can also be passed during subscription update. If they are passed, corresponding Billing Info attributes - the Billing Address and 'vat_number' - will be replaced automatically.
Passing credit card details to this API involves PCI liability at your end as sensitive card info passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable
- If you are using Stripe gateway, you can use Stripe.js with your checkout form. Take a look at this Stripe tutorial for more details.
- If you are using Braintree gateway, you can use Braintree.js with your checkout form. Please refer this tutorial for more details.
- If you are using Authorize.Net gateway, you use Accept.js with your checkout form.
- If you are using the Adyen gateway, you will have to use the Adyen's Client Side Encryption to encrypt sensitive cardholder data. Once the cardholder data is encrypted, pass the value in adyen.encrypted.data as temp token in this API.
- You can also use our Hosted Pages based integration.
Proration Scenario: A customer changes from a $15 plan to $30 plan after 15 days of a monthly term. He will be charged for $7.50 immediately. The following Credit Note and Invoice will be generated
| Credit Note | |
| Prorated credits for Old Plan | $7.50 |
| Invoice | |
| Prorated charges for New Plan | $15.00 |
| Total | $15.00 |
| Credits | ($7.50) |
| Amount Due | $7.50 |
Meanwhile downgrading will result in net credits being created which will be applied when the subscription is charged on start of the next term. Learn more about our proration scenarios here.
Billing Cycle: The billing period for a subscription does not change if the plans intervals of both old and new are same. However, if a customer changes to a plan that has different billing interval(say monthly to yearly), the billing period is reset. Customer is charged immediately for the modified subscription after applying credit for the unused period for the old subscription. Card and VAT number Input: If they are passed, corresponding Billing Address attributes and vat_number will be replaced. i.e existing values for Billing Address and 'vat_number' will be cleared and the new values will be set. If an invoice gets generated during this operation, available Credits and Excess Payments will be automatically applied.
Advance charges, if any, will be refunded as credits and a new invoice will be generated on renewal.
Sample Request
URL Format
Input Parameters
Amount that will override the plan's default price. The unit depends on the type of currency.
If changes_scheduled_at
is in the past and a plan_unit_price
is not passed, then the plan's current unit price is considered even if the plan did not exist on the date as of when the change is scheduled.
Amount that will override the default setup fee. The unit depends on the type of currency .
Should be true if the existing addons should be replaced with the ones that are being passed.
A list of IDs representing the mandatorily attached addons associated with the plan to which the subscription is being updated. These addons will be removed from the subscription during the subscription update process.
The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.
When price overriding
is enabled for the site, the price or per-unit price of the item can be set here. The value set for the item price
is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing
is enabled. If changes_scheduled_at
is in the past and a unit_price_in_decimal
is not passed, then the item price's current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.
The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices
is set to true
, and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date.
When passing this parameter, the following prerequisites must be met:
invoice_datemust be in the past.invoice_dateis not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.- It is not earlier than
changes_scheduled_at,reactivate_from, ortrial_end. invoice_immediatelyistrue. .
The new start date of a future
subscription. Applicable only for future
subscriptions.
The time at which the trial has ended or will end for the subscription. Set it to 0 to have no trial period.
Note
- This is only allowed when the subscription
statusisfuture,in_trial, orcancelled. - The value must not be earlier than
changes_scheduled_atorstart_date. - This parameter can be backdated (set to a value in the past) only when the subscription is in
cancelledorin_trialstatus. Do this to keep a record of when the trial ended in case it ended at some point in the past. Whentrial_endis backdated, the subscription immediately goes intoactiveornon_renewingstatus.
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used.
The number of subscription billing cycles to invoice in advance.
If a new term is started for the subscription due to this API call, then terms_to_charge
is inclusive of this new term. See description for the force_term_reset
parameter to learn more about when a subscription term is reset.
If the subscription status
is cancelled
and it is being reactivated via this operation, this is the date/time at which the subscription should be reactivated.
Note:
It is recommended not to pass this parameter along with changed_scheduled_at.
reactivate_from
can be backdated (set to a value in the past). Use backdating when the subscription has been reactivated already but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
- Backdating must be enabled for subscription reactivation operations.
- The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is the day of the month by which the accounting for the previous month must be closed.
- The date is on or after the last date/time any of the product catalog items of the subscription were changed.
- The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April,
changes_scheduled_atcannot be earlier than 14th February. .
Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
Subscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..
Subscription period will be aligned with the configured billing date at the next renewal.
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
Whenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.
Automatic collection of charges will not be made for this subscription. Use this for offline payments.
The preferred offline payment method for the subscription.
No Preference
Cash
Check
Bank Transfer
ACH Credit
List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.
If changes_scheduled_at
is in the past, then the currently available coupons can be used even if they were not available as of the date for when the change is scheduled.
If true
then the existing coupon_ids
list for the subscription is replaced by the one provided. If false
then the provided list gets added to the existing coupon_ids
.
- When
true: Prorated credits or charges are created as applicable for this change. - When
false: The subscription is changed without creating any credits or charges. - When not provided, the value configured in the site settings is considered.
Caveat
For further changes within the same billing term, when prorate is set to true, credits are not created when all the conditions below hold true:
An immediate previous change was made
- with
prorateset tofalseand - no changes were made to the subscription's billing term and
- a change was made to either the subscription's plan, its addons, or the prices of the plan or addons.
Set this to true if you want the update to be applied at the end of the current subscription billing cycle.
Say the subscription has the renewal date as 28th of every month. When the plan-item price of the subscription is set to one that has the same billing period as the current plan-item price, the subscription change does not change the term. In other words, the subscription still renews on the 28th. Passing this parameter as true
will have the subscription reset its term to the current date (provided end_of_term
is false).
Note:
When the new plan-item price has a billing period different from the current plan-item price of the subscription, the term is always reset, regardless of the value passed for this parameter.
When the status
of the subscription is cancelled
, this parameter determines whether the subscription is reactivated upon making this API request. Unless passed explicitly as false
, this parameter is implied as true
when you provide plan_id
or addons[id]
The Chargebee payment token generated by Chargebee JS.
Note:
The payment token created via Chargebee JS uses the gateway selected through Smart Routing.
Explicitly passing a gateway_id
in this API call will not override the gateway associated with the token.
A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.
A collection of key-value pairs that provides extra information about the subscription.
Note: There's a character limit of 65,535.
If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges. The default value is as per the site settings .
Note:
invoice_immediately
only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.
.
If true
, ignores the hierarchy relationship
and uses customer as payment and invoice owner.
When change_option
is set to specific_date
, then set the date/time at which the subscription change is to happen or has happened. Note:
It is recommended not to pass this parameter along with reactivate_from.
changes_scheduled_at
can be set to a value in the past. This is called backdating the subscription change and is performed when the subscription change has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
-
Backdating must be enabled for subscription change operations.
-
Only the following changes can be backdated:
-
Changes in the recurring items or their prices.
-
Addition of non-recurring items.
-
Subscription
statusisactive,cancelled, ornon_renewing. -
The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is typically the day of the month by which the accounting for the previous month must be closed.
-
The date is on or after
current_term_start. -
The date is on or after the last date/time any of the following changes were made:
-
Changes in the recurring items or their prices.
-
Addition of non-recurring items.
-
The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April,
changes_scheduled_atcannot be earlier than 14th February..
Note:
The changes_scheduled_at
parameter does not apply to auto_collection
, shipping_address
, and po_number
; these parameters take effect immediately
when scheduling a subscription update.
When the quote is converted, this attribute determines the date/time as of when the subscription change is to be carried out.
The change is carried out immediately.
The change is carried out at the end of the current billing cycle of the subscription.
The change is carried out as of the date specified under changes_scheduled_at
.
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles
or a custom value depending on the site configuration
.
The period of time by which the first term of the subscription is to be extended free-of-charge. The value must be in multiples of free_period_unit.
The unit of time in multiples of which the free_period parameter is expressed. The value must be equal to or lower than the period_unit attribute of the plan chosen.
Charge based on day(s)
Charge based on week(s)
Charge based on month(s)
Charge based on year(s)
Applicable only when End-of-trial Action has been enabled for the site. Whenever the subscription has a trial period, this attribute (parameter) is returned (required) and specifies the operation to be carried out for the subscription once the trial ends.
This is the default value. The action configured for the site at the time when the trial ends, takes effect.
The action configured for the site at the time when the trial ends, takes effect.
The subscription activates and charges are raised for non-metered items.
The subscription cancels.
Returns
Resource object representing subscription
Resource object representing customer
Resource object representing card
Resource object representing invoice
Resource object representing unbilled_charge
Resource object representing credit_note