Note:
- This endpoint optionally supports 3DS. To use it, create a
payment_intentand provide it via this endpoint. - 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.
Caution
If the subscription currently includes ramps, it's important to note that any ramps scheduled may move to the draft status due to changes in plan billing frequency, line item, or term end. Carefully review your ramp configurations and the details of the subscription update to prevent any unintended disruptions to the subscription.
Updates the specified subscription by setting the parameters passed. Any parameters not provided are left unmodified. If an invoice is generated for this operation, any available credits and excess payments for the customer are automatically applied.
Sample Request
URL Format
Input Parameters
A list of item 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.
If true
then the existing subscription_items
list for the subscription is replaced by the one provided. If false
then the provided subscription_items
list gets added to the existing list.
Updates Net D for the subscription. Net D is the number of days within which any invoice raised for the subscription must be paid.
- If the value is
0or a positive integer: Net D is set explicitly for the subscription to the value provided. The value must be one of those defined in the site configuration. - If the value is
-1: The attribute is reset and therefore not returned by the API. In this case, when an invoice is raised - whether now or later - thenet_term_daysdefined at the customer level is considered. - If the value is not provided: The attribute is left unaltered. .
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 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.
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 items or their prices.
Caution This parameter is unavailable when the Subscription Ramps feature is enabled; use Create a ramp API instead.
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.
Constraints
If you pass force_term_reset, you must also pass invoice_usages with the same value when all of the following site configuration settings are enabled:
- Usage-based billing
- Mid-term changes for usage-based items
- Invoice and charge for usage-based items when a subscription is changing
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 the subscription_items
and coupons
parameters.
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.
Caution This parameter cannot be set to a future date when the Subscription Ramps feature is enabled; use Create a ramp API instead.
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.
Specifies the effective date for the subscription change.
The change is carried out immediately.
The change is carried out at the end of the current billing cycle of the subscription.
Executes the change on a specified date. The change occurs as of the date/time defined in changes_scheduled_at.
Caution
The end_of_term option is unavailable and specific_date cannot be set to a future date when the Subscription Ramps feature is enabled; use Create a ramp API instead.
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)
Indicates whether the invoices for this subscription are generated with a pending status. This attribute is set to true automatically when the subscription has item prices that belong to metered items.
You can also set this to true explicitly using the create/update subscription operations. This is useful in the following scenarios:
- When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as a one-time charge at the end of the billing term.
- When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site .
Set to false
to override for this subscription, the site-level setting
for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at the customer level
.
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.
The type of initiator to be used for the payment request triggered by this operation.
Pass this value to indicate that the request is initiated by the customer
Pass this value to indicate that the request is initiated by the merchant
Setting this attribute to true will invoice the overages for the metered items during the subscription change.
Constraints
If you pass invoice_usages, you must also pass force_term_reset with the same value when all of the following site configuration settings are enabled:
- Usage-based billing
- Mid-term changes for usage-based items
- Invoice and charge for usage-based items when a subscription is changing
Specify limits on how credits and payments are applied to individual invoices for the subscription. Contact Support to enable this feature. Note: These limits do not apply to consolidated invoices .
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