Pricing Templates
Log in Sign up
Integrations / Chargebee Product / ...

POST /subscriptions/{subscription-id}/update_for_items

Updates a subscription by modifying its item prices, coupons, billing configuration, payment method, and other attributes. Any parameters not provided remain unchanged. The changes can be applied immediately, scheduled for a future date, or even backdated to a past date.

Impacts

Subscription and Ramps: Impact on existing scheduled changes

  • If the subscription has existing scheduled changes, the behavior depends on whether Ramps are enabled:
    • Ramps disabled: Any existing scheduled change on the subscription is deleted.
    • Ramps enabled with compatibility mode:
      • If only one ramp is present:
        • If the ramp was created using this API, the ramp is deleted.
        • If the ramp was created using the Create a ramp API, and the date-time of the new change is before the date-time of the ramp, then the ramp is moved to draft status if the auto-draft conditions are met.
      • If multiple ramps are present: all ramps after the date-time of the new change are moved to draft status if the auto-draft conditions are met.
  • For more details, see Ramps API compatibility mode.

Subscription: Other impacts

  • 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 are automatically removed during the subscription update to a new plan.

Invoice

  • If an invoice is generated, any available credits and excess payments for the customer are automatically applied subject to limits set at the site level, which can be overridden for subscriptions via subscription.billing_override.

Credit Note

  • When the subscription change occurs in the middle of a billing term, and prorate is true, prorated credits may be created for the unused service periods of the subscription items.

Payment Source

  • If payment_intent, payment_method, or card parameters are provided, a new payment source is created for the customer and associated with the subscription as the payment_source_id.

Use Cases

Add item prices to the subscription

To add new item prices to the subscription, pass them in the subscription_items parameter.

Example

Consider a subscription with the following item prices:

  • plan-a-monthly-usd
  • addon-b-monthly-usd

If you call this API with the following item price:

  • addon-c-monthly-usd

The subscription will be updated to include the following item prices:

  • plan-a-monthly-usd
  • addon-b-monthly-usd
  • addon-c-monthly-usd

Replace item prices in the subscription

To replace all existing item prices in the subscription with a new set of item prices, include the replace_items_list parameter and set it to true.

Example

Consider a subscription with the following item prices:

  • plan-a-monthly-usd
  • addon-b-monthly-usd

If you call this API with the following item prices and set replace_items_list to true:

  • plan-c-monthly-usd
  • addon-d-monthly-usd

The subscription will be updated to include only the new item prices:

  • plan-c-monthly-usd
  • addon-d-monthly-usd

Create payment source using payment_intent

Use the payment_intent parameter to create a payment source for the customer. Using payment intents is the recommended way to create a payment source in Chargebee for both Strong Customer Authentication (SCA) (i.e. 3D-Secure) and non-SCA flows.

  1. Create a payment_intent resource by calling the Create a payment intent API.
  2. Pass the payment_intent object to your frontend and use Chargebee.js to capture the payment source details from the customer. Use Payment Method Helpers to show payment method UIs and collect payment method details from the customer.
  3. Listen to the payment_intent_updated event. Once the payment_intent.status is authorized, pass the payment_intent.id using the payment_intent[id] parameter in this API call.

Create payment source using payment_method

If you prefer to use the payment gateway's SDKs to capture the payment method details, you can then use the payment_method parameter in this API to pass the payment method token and other details.

  1. Use the JavaScript library of your payment gateway to capture the payment method details. Examples include:
    • Stripe.js
    • Braintree.js
    • Accept.js (if you use Authorize.Net)
    • Adyen's Client-Side Encryption (if you use Adyen)
  2. Pass the payment method token using the payment_method[reference_id] or payment_method[tmp_token] parameter along with any additional parameters required by the payment gateway to create the payment source.

Create payment source using card

If you are PCI compliant, you can pass raw card details via this API. Use the card parameter to pass the card details.

Servers

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

Valid values:

  • "all-disabled"
chargebee-business-entity-id String No

If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
chargebee-event-actions String No

skip all actions to be done on the events

Valid 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

Valid values:

  • "all-disabled"

Request body fields

Name Type Required Description
discounts Object No

Parameters for discounts
discounts.apply_on[] Array No
discounts.included_in_mrr[] Array No

The discount is included in MRR calculations for your site. This attribute is only applicable when duration_type is one_time and when the feature is enabled in Chargebee. Also, If the site-level setting is to exclude one-time discounts from MRR calculations, this value is always returned false.
discounts.id[] Array No

The id of the discount to be removed. This parameter is only relevant when discounts[operation_type] is remove .
discounts.period_unit[] Array No
discounts.operation_type[] Array Yes
discounts.percentage[] Array No

The percentage of the original amount that should be deducted from it.
discounts.period[] Array No

The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
discounts.amount[] Array No

The value of the discount. The format of this value depends on the kind of currency.
discounts.duration_type[] Array Yes
discounts.item_price_id[] Array No

The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.
discounts.quantity[] Array No

Specifies the number of free units provided for the item, without affecting the total quantity sold
end_of_term Boolean No

Deprecated

  • This option is deprecated; use the Create a ramp API instead.
  • If you pass this parameter along with change_option, then change_option takes precedence.

This parameter has the same effect as setting the change_option parameter to end_of_term.

Default value: false
force_term_reset Boolean No

Forces the subscription term to start from the date of the subscription change when updating to a plan-item price with the same billing period as the current plan-item price.

Default value

  • false

Constraints

  • Only applicable when the new plan-item price has the same billing period as the current plan-item price. When the billing period differs, the term is always reset regardless of this parameter's value.
  • Only takes effect when end_of_term is false.
  • 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

Default value: false
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.
payment_method Object No

Use this parameter if you prefer to use the payment gateway's SDKs to capture the payment method details and pass the payment method token and other details here. See [use cases](/docs/api/subscription/update-subscription-for-items#use-cases) to learn more.
payment_method.gateway_account_id String No

The gateway account in which this payment source is stored.
payment_method.type String No

The type of payment method. For more details refer Update payment method for a customer API under Customer resource. * google_pay -

Payments made via Google Pay. * pix -

Payments made via Pix * pay_by_bank -

Pay By Bank * sofort -

Payments made via Sofort. * netbanking_emandates -

Netbanking (eMandates) Payments. * apple_pay -

Payments made via Apple Pay. * unionpay -

Payments made via UnionPay. * giropay -

Payments made via giropay. * direct_debit -

Represents bank account for which the direct debit or ACH agreement/mandate is created. * bancontact -

Payments made via Bancontact Card. * upi -

UPI Payments. * stablecoin -

Payments made via Stablecoin * alipay -

Payments made via Alipay.
This payment source is deprecated. * pay_to -

Payments made via PayTo * wechat_pay -

Payments made via WeChat Pay.
This payment source is deprecated. * sepa_instant_transfer -

Payments made via Sepa Instant Transfer * dotpay -

Payments made via Dotpay. * paypal_express_checkout -

Payments made via PayPal Express Checkout. * ideal -

Payments made via iDEAL. * electronic_payment_standard -

Electronic Payment Standard * generic -

Payments made via Generic Payment Method. * klarna_pay_now -

Payments made via Klarna Pay Now * faster_payments -

Payments made via Faster Payments * venmo -

Payments made via Venmo * payconiq_by_bancontact -

Payments made via Payconiq by Bancontact * 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. * online_banking_poland -

Payments made via Online Banking Poland * trustly -

Trustly * kbc_payment_button -

KBC Payment Button

Valid values:

  • "pay_by_bank"
  • "upi"
  • "online_banking_poland"
  • "cash_app_pay"
  • "unionpay"
  • "direct_debit"
  • "netbanking_emandates"
  • "giropay"
  • "electronic_payment_standard"
  • "venmo"
  • "payconiq_by_bancontact"
  • "card"
  • "klarna_pay_now"
  • "pix"
  • "faster_payments"
  • "sepa_instant_transfer"
  • "alipay"
  • "naver_pay"
  • "revolut_pay"
  • "bancontact"
  • "amazon_payments"
  • "trustly"
  • "sofort"
  • "automated_bank_transfer"
  • "stablecoin"
  • "kakao_pay"
  • "paypal_express_checkout"
  • "apple_pay"
  • "pay_to"
  • "generic"
  • "kbc_payment_button"
  • "dotpay"
  • "google_pay"
  • "wechat_pay"
  • "ideal"
payment_method.tmp_token String No

Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
payment_method.issuing_country String No

ISO 3166 alpha-2 country code .

Note: If you enter an invalid country code, the system will return an error.

If you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland ) is available as an option.
payment_method.additional_information Object No

  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.

    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user's payment method may not be the same as their country of residence. Hence the user's country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user's identification number based on their country.

  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.

  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.

  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

  • bank_of_america: While passing raw card details to Bank of America, your user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.

  • ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part.

    • merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.

  • ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • payer: User related information.
      • document: Document is the user's identification number based on their country.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device
payment_method.reference_id String No

The reference id. In the case of Amazon and PayPal this will be the billing agreement id . For GoCardless direct debit this will be 'mandate 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.
override_relationship Boolean No

If true , ignores the hierarchy relationship and uses customer as payment and invoice owner.
subscription_items Object No

The list of item prices to add or update in the subscription.

Note See replace_items_list for more details.
subscription_items.unit_price[] Array No

The price or per-unit price of the item. Overrides the price set for the item price.

Prerequisites

  • The pricing_model of the item price must be flat_fee or per_unit.
  • Price overriding must be enabled for the site.

Default value

  • The value set for the item price is used when not provided.
  • If changes_scheduled_at is in the past and unit_price is not passed, the item price's current unit price is considered even if the item price did not exist on the date.
subscription_items.charge_once[] Array No

Indicates if the charge-item is to be charged only once or each time the charge_on_event occurs. This parameter only applies to charge-items.
subscription_items.unit_price_in_decimal[] Array No

The decimal representation of the price or per-unit price of the item. Overrides the price set for the item price.

Prerequisites

  • Price overriding must be enabled for the site.
  • Multi-decimal pricing must be enabled.

Default value

  • The value set for the item price is used when not provided.
  • If changes_scheduled_at is in the past and unit_price_in_decimal is not passed, the item price's current unit price is considered even if the item price did not exist on the date.

Constraints

  • Provide the value as a decimal string in major units of the currency.
subscription_items.item_price_id[] Array Yes

The unique identifier of the item price to add or update in the subscription.
Constraints

  • The item price currency must match the subscription's currency.
subscription_items.quantity[] Array No

The quantity of the item price purchased.

Prerequisites

  • The item price pricing_model must be per_unit, stairstep, or tiered.
subscription_items.quantity_in_decimal[] Array No

The decimal representation of the quantity of the item purchased.

Prerequisites

  • The item price pricing_model must be per_unit, stairstep, or tiered.
  • Multi-decimal pricing must be enabled.
subscription_items.billing_cycles[] Array No

For plan-item prices: The number of billing cycles the subscription runs before canceling automatically.

For addon-item prices: The number of subscription billing cycles for which the addon is included. Only applicable when addon billing cycles are enabled.
Default value

  • For plan-item prices: The value set for the item price is used.
  • For addon-item prices: The value set under attached addons is used. If that value is not provided, the value set for the item price is used.
subscription_items.charge_on_event[] Array No
subscription_items.charge_on_option[] Array No
subscription_items.proration_type[] Array No
subscription_items.service_period_days[] Array No

The service period of the item in days from the day of charge.
subscription_items.trial_end[] Array No

The date/time when the trial period of the item ends. Applies to plan-items and--when enabled --addon-items as well.
subscription_items.usage_accumulation_reset_frequency[] Array No
coupon_ids[] Array No

The list of coupons to be applied to this subscription. You can provide coupon IDs or coupon codes.

Note

  • If changes_scheduled_at is in the past, you can use currently available coupons even if those coupons were not available on the date of the change.
prorate Boolean No

When this subscription change is set to occur in the middle of the subscription term, prorate determines whether prorated credits and charges are created for the change.

  • 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.

Default value

The value configured in the site settings is used when not provided.

Constraints

If you set prorate to true for a change made mid-term in the billing cycle, credits are not created if all of the following were true for a previous change in the same billing term:
  • The earlier change had prorate set to false.
  • No changes were made to the subscription's billing term.
  • Only the subscription's items or their prices were updated.
invoice_immediately Boolean No

Determines whether charges raised immediately for the subscription are invoiced immediately or added to unbilled charges.
Default value

  • The value configured in the site settings is used when not provided.
    Note:

  • Any charges scheduled to be raised in the future are not affected by this parameter.
billing_override Object No

Specify limits on how credits and payments are applied to individual invoices for the subscription. Contact [Support](https://support.chargebee.com/) to enable this feature. Note: These limits do not apply to [consolidated invoices](https://www.chargebee.com/docs/2.0/consolidated-invoicing.html) .
billing_override.max_excess_payment_usage Integer No

Maximum amount of excess payments that can be applied to any single invoice associated with this subscription. Set to -1 to auto-apply without limit, 0 to prevent auto-application, or any positive value to define the maximum amount that can be applied.
billing_override.max_refundable_credits_usage Integer No

Maximum amount of refundable credits that can be applied to any single invoice associated with this subscription. Set to -1 to auto-apply without limit, 0 to prevent auto-application, or any positive value to define the maximum amount that can be applied.
net_term_days Integer No

Updates Net D for the subscription. Net D is the number of days within which any invoice raised for the subscription must be paid.

Constraints

  • The value must match one of the options defined in your site configuration.
  • To reset this attribute, set the value to -1. When reset, it is not returned by the API, and the net_term_days value set at the customer level is used instead.
start_date Integer No

The new start date of a future subscription.

Prerequisites

  • The subscription status must be future.
free_period Integer No

The period of time by which the first billing term after trial is extended free of charge. The value is expressed in the time unit specified by free_period_unit. For example, 3 with free_period_unit = month adds 3 free months to the first paid term when the subscription becomes active.
changes_scheduled_at Integer No

The date-time at which the subscription change is to happen or has happened.

Deprecated for scheduling changes

  • Setting this parameter to a future date-time for scheduling changes is deprecated. Use the Create a ramp API instead.

Required if

  • change_option is set to specific_date.

Constraints

  • Do not pass this parameter along with reactivate_from.

Backdated changes

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 status is active, cancelled, or non_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.
auto_collection String No

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property. * on -

Whenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available. * off -

Automatic collection of charges will not be made for this subscription. Use this for offline payments.

Valid values:

  • "on"
  • "off"
replace_coupon_list Boolean No

Determines whether the provided coupon_ids replace or add to the existing coupons on the subscription.

Default value

  • false (the provided coupons are added to the existing coupons)

Default value: false
reactivate_from Integer No

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_at cannot be earlier than 14th February.
reactivate Boolean No

Determines whether to reactivate a cancelled subscription when making this API request.

Default value

  • true when subscription_items or coupons are provided, unless explicitly set to false.

Required if

  • The subscription status is cancelled and you want to reactivate it.
statement_descriptor Object No

Parameters for statement_descriptor
statement_descriptor.descriptor String No

Payment transaction descriptor text to help your customer easily recognize the transaction. When this value is passed this will override the transaction descriptor text configured in the Chargebee site for all the subscription renewal transactions.
contract_term Object No

Parameters for contract_term
contract_term.action_at_term_end String No

Action to be taken when the contract term completes.

* renew_once -

Used when you want to renew the contract term just once. Does the following: - Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

  • The action_at_term_end for the new contract term is set to cancel.
* cancel -

Contract term completes and subscription is canceled.

* evergreen -

Contract term completes and the subscription renews.

* renew -
  • Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.
  • The action_at_term_end for the new contract term is set to renew.

Valid values:

  • "renew_once"
  • "evergreen"
  • "cancel"
  • "renew"

Default value: "renew"
contract_term.cancellation_cutoff_period Integer No

The number of days before contract_end , during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
free_period_unit String No

The time unit for free_period.

Constraints

Must be equal to or lower than the period_unit of the plan item price of the subscription.
* week -

Charge based on week(s)

* month -

Charge based on month(s)

* day -

Charge based on day(s)

* year -

Charge based on year(s)

Valid values:

  • "month"
  • "day"
  • "week"
  • "year"
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.validation_status String No

The address verification status. * valid -

Address was validated successfully. * partially_valid -

The address is valid for taxability but has not been validated for shipping. * invalid -

Address is invalid. * not_validated -

Address is not yet validated.

Valid values:

  • "partially_valid"
  • "valid"
  • "not_validated"
  • "invalid"

Default value: "not_validated"
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.
payment_initiator String No

The type of initiator to be used for the payment request triggered by this operation. * customer -

Pass this value to indicate that the request is initiated by the customer * merchant -

Pass this value to indicate that the request is initiated by the merchant

Valid values:

  • "merchant"
  • "customer"
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.validation_status String No

The address verification status. * not_validated -

Address is not yet validated. * valid -

Address was validated successfully. * partially_valid -

The address is valid for taxability but has not been validated for shipping. * invalid -

Address is invalid.

Valid values:

  • "partially_valid"
  • "valid"
  • "not_validated"
  • "invalid"

Default value: "not_validated"
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.
token_id String No

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.
po_number String No

Purchase order number for this subscription.
meta_data Object No

A collection of [key-value pairs](advanced-features#metadata) that provides extra information about the subscription. **Constraints** * There's a character limit of 65,535.
payment_intent Object No

Pass these parameters to create a new payment_source using an authorized payment_intent. This is the recommended way to create a payment source in Chargebee for both Strong Customer Authentication (SCA) (i.e. 3D-Secure) and non-SCA flows. See use cases to learn more.
payment_intent.id String No

Identifier for the payment_intent resource. If you provide this parameter, you do not need to pass other payment_intent parameters.

Prerequisites

  • The value of payment_intent.status must be authorized.
payment_intent.gateway_account_id String No

The gateway account used for performing the 3DS flow.
payment_intent.payment_method_type String No

The payment method type.

Default value

  • card
* card -

card

* dotpay -

dotpay

* faster_payments -

Faster Payments

* upi -

upi

* kbc_payment_button -

KBC Payment Button

* google_pay -

google_pay

* paypal_express_checkout -

paypal_express_checkout

* pix -

Pix

* klarna_pay_now -

Klarna Pay Now

* ideal -

ideal

* boleto -

boleto

* direct_debit -

direct_debit

* sepa_instant_transfer -

Sepa Instant Transfer

* bancontact -

bancontact

* trustly -

Trustly

* stablecoin -

Stablecoin

* venmo -

Venmo

* pay_to -

PayTo

* netbanking_emandates -

netbanking_emandates

* payconiq_by_bancontact -

Payconiq by Bancontact

* electronic_payment_standard -

Electronic Payment Standard

* pay_by_bank -

Pay By Bank

* apple_pay -

apple_pay

* online_banking_poland -

Online Banking Poland

* giropay -

giropay

* sofort -

sofort

* amazon_payments -

Amazon Payments

Valid values:

  • "pay_by_bank"
  • "upi"
  • "online_banking_poland"
  • "cash_app_pay"
  • "direct_debit"
  • "boleto"
  • "netbanking_emandates"
  • "giropay"
  • "electronic_payment_standard"
  • "venmo"
  • "payconiq_by_bancontact"
  • "card"
  • "klarna_pay_now"
  • "pix"
  • "faster_payments"
  • "sepa_instant_transfer"
  • "alipay"
  • "naver_pay"
  • "revolut_pay"
  • "bancontact"
  • "amazon_payments"
  • "trustly"
  • "sofort"
  • "stablecoin"
  • "kakao_pay"
  • "paypal_express_checkout"
  • "apple_pay"
  • "pay_to"
  • "kbc_payment_button"
  • "dotpay"
  • "google_pay"
  • "ideal"
  • "wechat_pay"
payment_intent.additional_information Object No

  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.

    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user's payment method may not be the same as their country of residence. Hence the user's country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user's identification number based on their country.

  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.

  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.

  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

  • bank_of_america: While passing raw card details to Bank of America, your user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.

  • ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part.

    • merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.

  • ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • payer: User related information.
      • document: Document is the user's identification number based on their country.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device
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.
terms_to_charge Integer No

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.
mandatory_items_to_remove[] Array No

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.
trial_end_action String No

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. * activate_subscription -

The subscription activates and charges are raised for non-metered items. * cancel_subscription -

The subscription cancels. * plan_default -

The action configured for the site at the time when the trial ends, takes effect. * site_default -

This is the default value. The action configured for the site at the time when the trial ends, takes effect.

Valid values:

  • "site_default"
  • "cancel_subscription"
  • "activate_subscription"
  • "plan_default"
card Object No

Parameters for card. Use this parameter to pass raw card details. Passing raw card data via API involves PCI liability at your end due to the sensitivity of the data.
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.number String No

The 16 digit credit card number.
If you are using Braintree.js, you can specify the Braintree encrypted card number here.
card.first_name String No

Cardholder's first name
card.expiry_month Integer No

Card expiry month.
card.additional_information Object No

  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.

    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user's payment method may not be the same as their country of residence. Hence the user's country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user's identification number based on their country.

  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.

  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.

  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

  • bank_of_america: While passing raw card details to Bank of America, your user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.

  • ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part.

    • merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.

  • ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions.

    • payer: User related information.
      • document: Document is the user's identification number based on their country.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device
card.last_name String No

Cardholder's last name
card.gateway_account_id String No

The gateway account in which these card details are stored.

Required when

  • All of the following conditions are met together:
  • Passing card parameter.
  • There are multiple payment gateway accounts configured for the site.
  • Smart Routing is not configured for card payments.
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.preferred_scheme String No

The customer's preferred card scheme for co-branded cards.
Note: Currently, this parameter is only supported for Stripe. * cartes_bancaires -

A Cartes Bancaires card scheme. * mastercard -

A MasterCard scheme. * visa -

A Visa card scheme.

Valid values:

  • "visa"
  • "cartes_bancaires"
  • "mastercard"
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.
replace_items_list Boolean No

Determines whether the provided subscription_items replace existing subscription items or are added to the existing list.

When subscription_items includes a plan

  • true: The entire subscription item list (plan and addons) is replaced by the provided list.
  • false: The provided items are added to the existing list. If multi-plan subscriptions is disabled, the existing plan item price is replaced. If multi-plan subscriptions is enabled, the existing plan item price is retained.

When subscription_items contains only addons

  • The existing plan on the subscription is always retained; it is not replaced.
  • true: Existing addons are replaced by the provided addons, except mandatory addons (auto-attached to the plan). Mandatory addons are kept unless you list them in mandatory_items_to_remove. The subscription will have the current plan, the addons you passed, plus any existing mandatory addons not in mandatory_items_to_remove.
  • false: The provided addons are added to the existing addons.

Default value: false
auto_close_invoices Boolean No

Overrides the site-level setting for auto-closing invoices for this subscription.
Prerequisites

  • Auto-closing invoices must be enabled for the site.
    Constraints

  • This attribute has a higher precedence than the same attribute at the customer level.
billing_cycles Integer No

The number of billing cycles the subscription runs before canceling automatically.
Default value

  • The value set for the plan-item price is used when not provided.
invoice_usages Boolean No

Determines whether to invoice the overages for metered items during the subscription change.

Prerequisites

  • Usage-based billing must be enabled.

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:
    • Mid-term changes for usage-based items
    • Invoice and charge for usage-based items when a subscription is changing

Default value: false
offline_payment_method String No

The preferred offline payment method for the subscription. * sepa_credit -

SEPA Credit * cash -

Cash * no_preference -

No Preference * bank_transfer -

Bank Transfer * check -

Check * eu_automated_bank_transfer -

EU Automated Bank Transfer * jp_automated_bank_transfer -

JP Automated Bank Transfer * uk_automated_bank_transfer -

UK Automated Bank Transfer * custom -

Custom * boleto -

Boleto * mx_automated_bank_transfer -

MX Automated Bank Transfer * us_automated_bank_transfer -

US Automated Bank Transfer * ach_credit -

ACH Credit

Valid values:

  • "mx_automated_bank_transfer"
  • "cash"
  • "boleto"
  • "no_preference"
  • "bank_transfer"
  • "jp_automated_bank_transfer"
  • "custom"
  • "check"
  • "eu_automated_bank_transfer"
  • "sepa_credit"
  • "ach_credit"
  • "us_automated_bank_transfer"
  • "uk_automated_bank_transfer"
create_pending_invoices Boolean No

Determines whether invoices for this subscription are generated with a pending status.

Prerequisites

  • Metered Billing must be enabled for the site.

Default behavior

  • Set to true automatically when the subscription has item prices that belong to metered items.

Use case

  • Pending invoices allow you to inspect all charges on each invoice before closing it.
customer Object No

Parameters for customer
customer.vat_number_prefix String No

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address

country as XI. That's the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.
customer.entity_identifier_standard String No

The standard used for specifying the entity_identifier_scheme. Currently only iso6523-actorid-upis is supported and is used by default when not provided.

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.

Default value: "iso6523-actorid-upis"
customer.entity_identifier_scheme String No

The Peppol BIS scheme associated with the vat_number of the customer. This helps identify the specific type of customer entity. For example, DE:VAT is used for a German business entity while DE:LWID45 is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country. See list of possible values .

Tip:

If there are additional entity identifiers for the customer not associated with the vat_number, they can be provided as the entity_identifiers[] array.
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 .
customer.is_einvoice_enabled Boolean No

Determines whether the customer is e-invoiced. When set to true or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country ). When set to false , the customer is not e-invoiced even if e-invoicing is enabled for their country.

Tip:

It is possible to set a value for this flag even when E-Invoicing is disabled. However, it comes into effect only when E-Invoicing is enabled.
customer.einvoicing_method String No

Determines whether to send einvoice manually or automatic. * automatic -

Use this value to send e-invoice every time an invoice or credit note is created. * manual -

When manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API. * site_default -

The default value of the site which can be overridden at the customer level.

Valid values:

  • "manual"
  • "site_default"
  • "automatic"
customer.business_customer_without_vat_number Boolean No

Confirms that a customer is a valid business without an EU/UK VAT number.
customer.registered_for_gst Boolean No

Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.
billing_alignment_mode String No

Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing. * immediate -

Subscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly. * delayed -

Subscription period will be aligned with the configured billing date at the next renewal.

Valid values:

  • "immediate"
  • "delayed"
item_tiers Object No

Parameters for item_tiers
item_tiers.starting_unit_in_decimal[] Array No

The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered , volume or stairstep and multi-decimal pricing is enabled.
item_tiers.price_in_decimal[] Array No

The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep , it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
item_tiers.package_size[] Array No

Package size for the tier when pricing type is package. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
item_tiers.price[] Array No

The overridden price of the tier. The value depends on the type of currency .
item_tiers.ending_unit[] Array No

The highest value in the quantity tier.
item_tiers.item_price_id[] Array No

The id of the item price for which the tier price is being overridden.
item_tiers.pricing_type[] Array No
item_tiers.starting_unit[] Array No

The lowest value in the quantity tier.
item_tiers.ending_unit_in_decimal[] Array No

The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered , volume or stairstep and multi-decimal pricing is enabled.
invoice_date Integer No

The document date displayed on the invoice PDF. Use this parameter to backdate the invoice for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date.

Prerequisites

  • invoice_immediately must be true.

Default value

  • The current date is used when not provided.

Constraints

  • Must be a date-timein the past.
  • Must not be more than one calendar month into the past. For example, if today is 13th January, you cannot pass a value that is earlier than 13th December.
  • It must not be earlier than changes_scheduled_at, reactivate_from, or trial_end.

Impacts

  • taxes[] and line_item_taxes[] are computed based on the tax configuration as of invoice_date.
  • 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.
trial_end Integer No

The time at which the trial has ended or will end for the subscription. Set to 0 to have no trial period.

Constraints

  • This is only allowed when the subscription status is future, in_trial, or cancelled.
  • The value must not be earlier than changes_scheduled_at or start_date.
  • 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.

Impact

  • When trial_end is backdated, the subscription immediately goes into active or non_renewing status.
contract_term_billing_cycle_on_renewal Integer No

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 .
change_option String No

Specifies when the subscription change takes effect.

Constraints

Regardless of the value of the change_option parameter, the following parameters always take effect immediately:
  • auto_collection
  • shipping_address
  • po_number
  • Any subscription-level custom field parameters

See also

  • Impacts on existing scheduled changes.
* end_of_term -

Deprecated This option is deprecated; use the Create a ramp API instead.

The change is carried out at the end of the current billing cycle of the subscription.

* specific_date -

Deprecated for scheduling changes This option is deprecated for scheduling changes to occur at a future date-time, use the Create a ramp API instead.

Executes the change on a specified date. The change occurs as of the date-time defined in changes_scheduled_at.

* immediately -

The subscription change takes effect immediately.

Valid values:

  • "end_of_term"
  • "immediately"
  • "specific_date"

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. 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.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2026 SimWorkflow
Terms of Service Privacy Policy