ChargebeeAPI

Estimate for updating a subscription

Try in API Explorer

Returns an estimate for updating a subscription.

In the response,

  • subscription_estimate: The details of the changed subscription such as status, next billing date, and so on.
  • invoice_estimate:The details of the immediate invoice, if it is generated. An immediate invoice is not generated when:
    • end_of_term parameter is true
    • prorate parameter is false
    • No changes are made to the plan item prices or addon item prices in subscription_items.
    • For changes such as quantity downgrades.
  • next_invoice_estimate:The details of the invoice to be generated later (if any) on the occasion that no immediate invoice has been generated.
  • credit_note_estimates:The list of credit notes (if any) generated during this operation.
  • unbilled_charge_estimates: The details of charges that have not been invoiced. This is returned only if the invoice_immediately parameter is set to false.

The following conditions must be met or tax calculation is ignored:

  • The taxability attribute for the customer is true.
  • Necessary parameters for tax calculation such as the following are passed: billing_address, shipping_address, customer[vat_number]

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/estimates/update_subscription_for_items

Input Parameters

changes_scheduled_at
optional, timestamp(UTC) in seconds

Caution This parameter is unavailable when the Subscription Ramps feature is enabled; use Create a ramp API instead.

When change_option is set to specific_date , then set the date/time at which the subscription change is to happen or has happened. Note: It is recommended not to pass this parameter along with reactivate_from. changes_scheduled_at can be set to a value in the past. This is called backdating the subscription change and is performed when the subscription change has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

  • Backdating must be enabled for subscription change operations.

  • Only the following changes can be backdated:

  • Changes in the recurring items or their prices.

  • Addition of non-recurring items.

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

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

change_option
optional, enumerated string

Specifies the effective date for the subscription change.

Possible Enum Values
immediately

The change is carried out immediately.

end_of_term

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

specific_date

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

Caution The end_of_term and specific_date options are unavailable when the Subscription Ramps feature is enabled; use Create a ramp API instead.

mandatory_items_to_remove
optional, string

Item ids of mandatorily attached addons that are to be removed from the subscription.

replace_items_list
optional, boolean, default=false

If true then the existing subscription_items list for the subscription is replaced by the one provided. If false then the provided subscription_items list gets added to the existing list.

invoice_date
optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices is set to true , and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

  • invoice_date must be in the past.
  • invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
  • It is not earlier than changes_scheduled_at, reactivate_from, or trial_end.
  • invoice_immediately is true. .
billing_cycles
optional, integer, min=0

Billing cycles set for plan-item price is used by default.

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.

coupon_ids
optional, string

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes .

replace_coupon_list
optional, boolean, default=false

If true then the existing coupon_ids list for the subscription is replaced by the one provided. If false then the provided list gets added to the existing coupon_ids .

prorate
optional, boolean
  • 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 items or their prices.
end_of_term
optional, boolean, default=false

Set this to true if you want the update to be applied at the end of the current subscription billing cycle.

force_term_reset
optional, boolean, default=false

Say the subscription has the renewal date as 28th of every month. When the plan-item price of the subscription is set to one that has the same billing period as the current plan-item price, the subscription change does not change the term. In other words, the subscription still renews on the 28th. Passing this parameter as true will have the subscription reset its term to the current date (provided end_of_term is false). Note: When the new plan-item price has a billing period different from the current plan-item price of the subscription, the term is always reset, regardless of the value passed for this parameter.

reactivate
optional, boolean

Applicable only for cancelled subscriptions. When passed as true , the canceled subscription is activated; otherwise subscription changes are made without changing its status. If not passed, subscription will be activated only if subscription_items is passed.

include_delayed_charges
optional, boolean, default=false

If true, all the unbilled charges will be included for the invoice estimate.

use_existing_balances
optional, boolean, default=true

The generated invoice_estimate/next_invoice_estimate will include all the balances - Promotional Credits, Refundable Credits, and Excess Payments - if any. If you don't want these balances to be included you can specify 'false' for the parameter use_existing_balances .

invoice_immediately
optional, boolean

If there are charges raised immediately for the subscription, this parameter specifies whether those charges are to be invoiced immediately or added to unbilled charges. The default value is as per the site settings .

Note: invoice_immediately only affects charges that are raised at the time of execution of this API call. Any charges scheduled to be raised in the future are not affected by this parameter.

.

invoice_usages
optional, boolean, default=false

Setting this attribute to true will invoice the overages for the metered item during subscription changes .

subscription
optional, string

Parameters for subscription

billing_address
optional, string

Parameters for billing_address

shipping_address
optional, string

Parameters for shipping_address

customer
optional, string

Parameters for customer

billing_override
optional, long

Parameters for billing_override

subscription_items
optional, string

Parameters for subscription_items

discounts
optional, enumerated string

Parameters for discounts

item_tiers
optional, string

Parameters for item_tiers

Returns

estimateEstimate object

Resource object representing estimate