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.
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.
- 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 billed a total of $7.50 immediately. Calculation will be as follows:
| Prorated Charge(New Plan) | $15.00 |
| Prorated Credit(Old Plan) for unused period | ($7.50) |
| Total prorated amount | $7.50 |
Downgrading will result in credit being created which will be applied when the subscription is charged on start of the next term.
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
Should be true if the existing addons should be replaced with the ones that are being passed.
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. This is only allowed when the subscription status
is future
, in_trial
, or cancelled.
Also, the value must not be earlier than changes_scheduled_at
or start_date.
Note:
This parameter can be backdated (set to a value in the past) only when the subscription is in cancelled
or in_trial
status.
Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end
is backdated, the subscription immediately goes into active
or non_renewing
status.
The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used.
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
Note:
When the coupon ID contains a special character; for example: #, the API returns an error. Make sure that you encode the coupon ID in the path parameter before making an API call.
.
- 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.
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 set of key-value pairs stored as additional information for the subscription. Learn more .
shipping_address[<param name>]