ChargebeeAPI

Create checkout to update a subscription

Idempotency Supported
Try in API Explorer

Create a Chargebee hosted page to accept payment details from a customer and checkout to update the subscription.

The following steps describe how best to use this API:

Provide item prices, coupons and a host of other details such as billing and shipping addresses to be prefilled for the customer on the checkout page. You may also provide pass_thru_content containing information and IDs from your systems that must be associated with the checkout page.

Warning The first item price in the list (parameter subscription_items[item_price_id][0]) must be an item_price of item_type plan.

  • Send the customer to the Checkout url received in the response. They can now add a payment method or use an existing one, to complete the checkout.

  • The subscription is updated and the customer is redirected to the redirect_url with the id and state attributes passed as query string parameters.
    Although the customer will be redirected to the redirect_url after successful checkout, we do not recommend relying on it for completing critical post-checkout actions. This is because redirection may not happen due to unforeseen reasons. Chargebee recommends listening to appropriate webhooks such as subscription_created or invoice_generated to verify a successful checkout.

  • Retrieve the hosted page at this stage to get the subscription and invoice details.

Billing address editing

If the billing_address attribute for the customer resource is already set, then the billing_address cannot be edited by the user during the Checkout session.

To allow customers to update their billing address, use one of the following options:

Chargebee Hosted Pages
  • Integrate Chargebee.js into your website or application. Use the openSection() function with options.sectionType set to ADDRESS to display the Customer Portal's address section.
  • Integrate the Customer Portal into your website or application. The Portal enables customers to manage their address information.
Customer API

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/hosted_pages/checkout_existing_for_items

Input Parameters

layout
optional, enumerated string

Specifies the checkout layout that overrides the default checkout layout configured in the Checkout & Self-Serve Portal settings.

Possible Enum Values
in_app

Indicates in-app checkout version

full_page

Indicates full page checkout version

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 coupon_ids list gets added to the existing list.

reactivate
optional, boolean

This parameter is only relevant for cancelled subscriptions. When set to true , it activates the canceled subscription; otherwise, subscription changes are applied without altering its status. Additionally, if not explicitly set and the subscription_items provided in the API differ from the existing items, the subscription will still be reactivated.

force_term_reset
optional, boolean, default=false

Note: This parameter is relevant only for subscriptions with status of active, non_renewing, or cancelled.

When you set this parameter to true, the subscription term resets to the date of the subscription change. By default, if you change the plan-item price to another with the same billing period, the subscription term remains unchanged. For example, if the subscription renews on the 28th of every month, it will continue to renew on the 28th after the change.

Note: If the new plan-item price has a different billing period from the current plan-item price, the subscription term resets automatically, regardless of the value of force_term_reset.

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

change_option
optional, enumerated string

Specifies the date or time when the subscription change will take effect after the quote is converted.

Possible Enum Values
immediately

The change will be carried out immediately.

end_of_term

The change will be carried out at the end of the current billing cycle of the subscription

specific_date

The change will be carried out on the date specified under changes_scheduled_at .

changes_scheduled_at
optional, timestamp(UTC) in seconds

When change_option is set to specific_date , specify the date and time for the subscription change to occur or to reflect a past change.

Note

  • It is recommended not to use this parameter alongside reactivate_from.
  • The changes_scheduled_at value cannot be set to a past date.

.

invoice_usages
optional, boolean, default=false

Setting this attribute to true will invoice the overages for the metered items during the subscription change.

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:

redirect_url
optional, string, max chars=250

The customers will be redirected to this URL upon successful checkout. The hosted page id and state will be passed as parameters to this URL.

Note :

  • Although the customer will be redirected to the redirect_url after successful checkout, we do not recommend relying on it for completing critical post-checkout actions. This is because redirection may not happen due to unforeseen reasons such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as subscription_created or invoice_generated to verify a successful checkout.
  • Redirect URL configured in Settings > Hosted Pages Settings would be overriden by this redirect URL.
  • Eg : http://yoursite.com?id=**&state=succeeded
  • This parameter is not applicable for iframe messaging.
cancel_url
optional, string, max chars=250

The customers will be redirected to this URL upon canceling checkout. The hosted page id and state will be passed as parameters to this URL.

Note : - Cancel URL configured in Settings > Hosted Pages Settings would be overriden by this cancel URL.
Eg : http://yoursite.com?id=&state=cancelled

  • This parameter is not applicable for iframe messaging and in-app checkout.
pass_thru_content
optional, string, max chars=2048

This attribute allows you to store custom information with the hosted_page object. You can use it to associate specific data with a hosted page session. For example, you can store the ID of the marketing campaign that initiated the user session. After a successful checkout, when the customer is redirected, you can retrieve the hosted page ID from the redirect URL's query parameters. Using this ID, you can fetch the hosted page and perform actions related to the success of the marketing campaign.

allow_offline_payment_methods
optional, boolean

Allow the customer to select an offline payment method during checkout. The choice of payment methods can be configured via the Chargebee UI.

subscription
optional, string

Parameters for subscription

customer
optional, string

Parameters for customer

card
optional, string

Parameters for card

contract_term
optional, enumerated string

Parameters for contract_term

subscription_items
optional, string

Parameters for subscription_items

discounts
optional, enumerated string

Parameters for discounts

item_tiers
optional, string

Parameters for item_tiers

entity_identifiers
optional, string

Parameters for entity_identifiers

Returns

hosted_pageHosted page object

Resource object representing hosted_page