ChargebeeAPI
Using AI coding agents like Claude Code or Cursor? Try the official Chargebee Agent Skills to speed up your development.Try now

Update subscription for items

Idempotency Supported
Try in API Explorer

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

Invoice

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

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/subscriptions/{subscription-id}/update_for_items

Input Parameters

mandatory_items_to_remove
optional, string, max chars=100

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.

replace_items_list
optional, boolean, default=false

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.
net_term_days
optional, integer

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.
invoice_date
optional, timestamp(UTC) in seconds

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.
start_date
optional, timestamp(UTC) in seconds

The new start date of a future subscription.

Prerequisites

  • The subscription status must be future.
trial_end
optional, timestamp(UTC) in seconds

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.
billing_cycles
optional, integer, min=0

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

Default value

terms_to_charge
optional, integer, min=1

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.

reactivate_from
optional, timestamp(UTC) in seconds

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.
billing_alignment_mode
optional, enumerated string

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

Possible Enum Values
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.

auto_collection
optional, enumerated string

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

Possible Enum Values
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.

offline_payment_method
optional, enumerated string

The preferred offline payment method for the subscription.

Possible Enum Values
no_preference

No Preference

cash

Cash

check

Check

bank_transfer

Bank Transfer

ach_credit

ACH Credit

po_number
optional, string, max chars=100

Purchase order number for this subscription.

coupon_ids
optional, string, max chars=100

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.
replace_coupon_list
optional, boolean, default=false

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)
prorate
optional, boolean

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.
end_of_term
optional, boolean, default=false

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.

force_term_reset
optional, boolean, default=false

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:
reactivate
optional, boolean

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.
token_id
optional, string, max chars=40

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.

invoice_notes
optional, string, max chars=2000

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.

meta_data
optional, jsonobject

A collection of key-value pairs that provides extra information about the subscription.

Constraints

  • There's a character limit of 65,535.
invoice_immediately
optional, boolean

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.
override_relationship
optional, boolean

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

changes_scheduled_at
optional, timestamp(UTC) in seconds

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.
change_option
optional, enumerated string

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

Possible Enum Values
immediately

The subscription change takes effect immediately.

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.

contract_term_billing_cycle_on_renewal
optional, integer, min=1, max=100

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 .

free_period
optional, integer, min=1

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.

free_period_unit
optional, enumerated string

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.

Possible Enum Values
day

Charge based on day(s)

week

Charge based on week(s)

month

Charge based on month(s)

year

Charge based on year(s)

create_pending_invoices
optional, boolean

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

Prerequisites

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.
auto_close_invoices
optional, boolean

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.
trial_end_action
optional, enumerated string

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.

Possible Enum Values
site_default

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

plan_default

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

activate_subscription

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

cancel_subscription

The subscription cancels.

payment_initiator
optional, enumerated string

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

Possible Enum Values
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

invoice_usages
optional, boolean, default=false

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

Prerequisites

Constraints

card
Parameters for card
pass parameters as card[<param name>]
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
statement_descriptor
Parameters for statement_descriptor
pass parameters as statement_descriptor[<param name>]
customer
Parameters for customer
pass parameters as customer[<param name>]
contract_term
Parameters for contract_term
pass parameters as contract_term[<param name>]
billing_override
Parameters for billing_override
pass parameters as billing_override[<param name>]
subscription_items[0..n]
Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]
discounts[0..n]
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
item_tiers[0..n]
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

Returns

subscriptionSubscription object
Resource object representing subscription
customerCustomer object
Resource object representing customer
cardCard object
Resource object representing card
invoiceInvoice object
Resource object representing invoice
unbilled_chargesoptional
Resource object representing unbilled_charge
credit_notesoptional
Resource object representing credit_note