POST /subscriptions/{subscription-id}

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.

Servers

{protocol}://{site}.{environment}:{port}/api/v1
{protocol}://{site}-test.{environment}:{port}/api/v1

Path parameters

Name	Type	Required	Description
`subscription-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`shipping_address`	Object	No	Parameters for shipping_address
`shipping_address.first_name`	String	No	The first name of the contact.
`shipping_address.state`	String	No	The state/province name. Is set by Chargebee automatically for US, Canada and India If `state_code` is provided.
`shipping_address.city`	String	No	The name of the city.
`shipping_address.line2`	String	No	Address line 2
`shipping_address.line1`	String	No	Address line 1
`shipping_address.email`	String	No	The email address.
`shipping_address.last_name`	String	No	The last name of the contact.
`shipping_address.company`	String	No	The company name.
`shipping_address.line3`	String	No	Address line 3
`shipping_address.state_code`	String	No	The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ`). For Tamil Nadu (India), set as `TN` (not `IN-TN`). For British Columbia (Canada), set as `BC` (not `CA-BC`).
`shipping_address.zip`	String	No	Zip or postal code. The number of characters is validated according to the rules specified here.
`shipping_address.phone`	String	No	The phone number.
`shipping_address.country`	String	No	The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code. Note : If you enter an invalid country code, the system will return an error. Brexit If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then `XI` (the code for United Kingdom -- Northern Ireland) is available as an option.
`end_of_term`	Boolean	No	Set this to true if you want the update to be applied at the end of the current subscription billing cycle. Default value: false
`po_number`	String	No	Purchase order number for this subscription.
`meta_data`	Object	No	A set of key-value pairs stored as additional information for the subscription. [Learn more](./#meta_data).
`payment_intent`	Object	No	Parameters for payment_intent
`payment_intent.id`	String	No	Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
`payment_intent.gateway_account_id`	String	No	The gateway account used for performing the 3DS flow.
`payment_intent.gw_token`	String	No	Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
`payment_intent.reference_id`	String	No	Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
`plan_id`	String	No	Identifier of the plan for this subscription.
`invoice_notes`	String	No	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.
`card`	Object	No	Parameters for card
`card.billing_addr2`	String	No	Address line 2, as available in card billing address.
`card.billing_addr1`	String	No	Address line 1, as available in card billing address.
`card.gateway`	String	No	Name of the gateway this payment source is stored with. * braintree - Braintree is a payment gateway. * pin - Pin is a payment gateway * authorize_net - Authorize.net is a payment gateway * nmi - NMI is a payment gateway. * not_applicable - Indicates that payment gateway is not applicable for this resource. * eway_rapid - eWAY Rapid is a payment gateway. * beanstream - Bambora(formerly known as Beanstream) is a payment gateway. * tco - 2Checkout is a payment gateway. * bluepay - BluePay is a payment gateway. * paypal_payflow_pro - PayPal Payflow Pro is a payment gateway. * paypal_pro - PayPal Pro Account is a payment gateway. * stripe - Stripe is a payment gateway. * sage_pay - Sage Pay is a payment gateway. * wirecard - WireCard Account is a payment service provider. * balanced_payments - Balanced is a payment gateway * migs - MasterCard Internet Gateway Service payment gateway. * paymill - PAYMILL is a payment gateway. * first_data_global - First Data Global Gateway Virtual Terminal Account * ogone - Ingenico ePayments (formerly known as Ogone) is a payment gateway. * chargebee - Chargebee test gateway. * worldpay - WorldPay is a payment gateway * hdfc - HDFC Account is a payment gateway. * elavon - Elavon Virtual Merchant is a payment solution. * eway - eWAY Account is a payment gateway. Possible values: `"balanced_payments"` `"first_data_global"` `"paymill"` `"bluepay"` `"paypal_payflow_pro"` `"wirecard"` `"nmi"` `"hdfc"` `"ogone"` `"stripe"` `"migs"` `"eway_rapid"` `"worldpay"` `"sage_pay"` `"beanstream"` `"tco"` `"paypal_pro"` `"braintree"` `"elavon"` `"chargebee"` `"pin"` `"eway"` `"authorize_net"`
`card.number`	String	No	The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
`card.ip_address`	String	No	The IP address of the customer. Used primarily for referral integration and EU VAT validation.
`card.first_name`	String	No	Cardholder's first name
`card.tmp_token`	String	No	The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return. Note: Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
`card.expiry_month`	Integer	No	Card expiry month.
`card.last_name`	String	No	Cardholder's last name
`card.billing_state_code`	String	No	The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ`). For Tamil Nadu (India), set as `TN` (not `IN-TN`). For British Columbia (Canada), set as `BC` (not `CA-BC`).
`card.billing_zip`	String	No	Postal or Zip code, as available in card billing address.
`card.expiry_year`	Integer	No	Card expiry year.
`card.cvv`	String	No	The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
`card.billing_city`	String	No	City, as available in card billing address.
`card.billing_state`	String	No	The state/province name. Is set by Chargebee automatically for US, Canada and India If `state_code` is provided.
`card.billing_country`	String	No	The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code. Note : If you enter an invalid country code, the system will return an error. Brexit If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then `XI` (the code for United Kingdom -- Northern Ireland) is available as an option.
`payment_method`	Object	No	Parameters for payment_method
`payment_method.gateway`	String	No	Name of the gateway the payment method is associated with. * chargebee - Chargebee test gateway. * stripe - Stripe is a payment gateway. * eway - eWAY Account is a payment gateway. * authorize_net - Authorize.net is a payment gateway * paypal_payflow_pro - PayPal Payflow Pro is a payment gateway. * sage_pay - Sage Pay is a payment gateway. * wirecard - WireCard Account is a payment service provider. * worldpay - WorldPay is a payment gateway * pin - Pin is a payment gateway * migs - MasterCard Internet Gateway Service payment gateway. * beanstream - Bambora(formerly known as Beanstream) is a payment gateway. * elavon - Elavon Virtual Merchant is a payment solution. * braintree - Braintree is a payment gateway. * nmi - NMI is a payment gateway. * first_data_global - First Data Global Gateway Virtual Terminal Account * bluepay - BluePay is a payment gateway. * paymill - PAYMILL is a payment gateway. * paypal_pro - PayPal Pro Account is a payment gateway. * eway_rapid - eWAY Rapid is a payment gateway. * ogone - Ingenico ePayments (formerly known as Ogone) is a payment gateway. * not_applicable - Indicates that payment gateway is not applicable for this resource. * tco - 2Checkout is a payment gateway. * hdfc - HDFC Account is a payment gateway. * balanced_payments - Balanced is a payment gateway Possible values: `"balanced_payments"` `"first_data_global"` `"paymill"` `"bluepay"` `"paypal_payflow_pro"` `"wirecard"` `"nmi"` `"hdfc"` `"ogone"` `"stripe"` `"migs"` `"eway_rapid"` `"worldpay"` `"sage_pay"` `"beanstream"` `"tco"` `"paypal_pro"` `"braintree"` `"elavon"` `"pin"` `"eway"` `"authorize_net"`
`payment_method.type`	String	No	The type of payment method. For more details refer Update payment method for a customer API under Customer resource. * paypal_express_checkout - Payments made via PayPal Express Checkout. * direct_debit - Represents bank account for which the direct debit or ACH agreement/mandate is created. * automated_bank_transfer - Represents virtual bank account using which the payment will be done. * amazon_payments - Payments made via Amazon Payments. * card - Card based payment including credit cards and debit cards. Details about the card can be obtained from the card resource. Possible values: `"amazon_payments"` `"card"` `"direct_debit"` `"automated_bank_transfer"` `"paypal_express_checkout"`
`payment_method.reference_id`	String	No	The reference id. In the case of Amazon and Paypal this will be the billing agreement id . In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one time temporary token provided by gateways like Stripe. For more details refer Update payment method for a customer API under Customer resource.
`billing_cycles`	Integer	No	The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan is used.
`prorate`	Boolean	No	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 `prorate` set to `false` and 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.
`customer`	Object	No	Parameters for customer
`customer.vat_number`	String	No	The VAT/tax registration number for the customer. For customers with billing_address `country` as `XI` (which is United Kingdom - Northern Ireland ), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.
`start_date`	Integer	No	The new start date of a `future` subscription. Applicable only for `future` subscriptions.
`coupon`	String	No	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. .
`replace_addon_list`	Boolean	No	Should be true if the existing addons should be replaced with the ones that are being passed. Default value: false
`trial_end`	Integer	No	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.
`plan_quantity`	Integer	No	Represents the plan quantity for this subscription. Default value: 1
`addons`	Object	No	Parameters for addons
`addons.id[]`	Array	No	Identifier of the addon. Multiple addons can be passed.
`addons.proration_type[]`	Array	No
`addons.quantity[]`	Array	No	Quantity of the addon. Applicable for addons with `pricing_model` other than `flat_fee`.
`billing_address`	Object	No	Parameters for billing_address
`billing_address.first_name`	String	No	The first name of the billing contact.
`billing_address.state`	String	No	The state/province name. Is set by Chargebee automatically for US, Canada and India If `state_code` is provided.
`billing_address.city`	String	No	The name of the city.
`billing_address.line2`	String	No	Address line 2
`billing_address.line1`	String	No	Address line 1
`billing_address.email`	String	No	The email address.
`billing_address.last_name`	String	No	The last name of the billing contact.
`billing_address.company`	String	No	The company name.
`billing_address.line3`	String	No	Address line 3
`billing_address.state_code`	String	No	The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ`). For Tamil Nadu (India), set as `TN` (not `IN-TN`). For British Columbia (Canada), set as `BC` (not `CA-BC`).
`billing_address.zip`	String	No	Zip or postal code. The number of characters is validated according to the rules specified here.
`billing_address.phone`	String	No	The phone number.
`billing_address.country`	String	No	The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code. Brexit If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then `XI` (the code for United Kingdom -- Northern Ireland) is available as an option.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.