POST /hosted_pages/checkout_existing_for_items

The device from which the customer has made the request

Default value: "application/x-www-form-urlencoded"

skip only webhooks

Possible values:

• "all-disabled"

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.

skip all actions to be done on the events

Possible values:

• "all-disabled"

The email address of your customer/user. Use this when the email address has only ASCII characters.

The IP address of the customer where the request originated

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.

skip only emails

Possible values:

• "all-disabled"

Parameters for discounts

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.

An immutable unique id for the discount. It is always auto-generated.

The percentage of the original amount that should be deducted from it.

The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.

The value of the discount. The format of this value depends on the kind of currency.

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.

Parameters for subscription

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

The preferred offline payment method for the subscription. * uk_automated_bank_transfer - UK Automated Bank Transfer * jp_automated_bank_transfer - JP Automated Bank Transfer * bank_transfer - Bank Transfer * us_automated_bank_transfer - US Automated Bank Transfer * boleto - Boleto * no_preference - No Preference * sepa_credit - SEPA Credit * mx_automated_bank_transfer - MX Automated Bank Transfer * ach_credit - ACH Credit * custom - Custom * eu_automated_bank_transfer - EU Automated Bank Transfer * cash - Cash * check - Check

Possible 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"

The new start date of a future subscription. Applicable only for future subscriptions.

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property. * off - Automatic collection of charges will not be made for this subscription. Use this for offline payments. * on - Whenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.

Possible values:

• "on"
• "off"

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.

The time at which the trial has ended or will end for the subscription. This is only allowed when the subscription status is future, in_trial, or cancelled. Also, the value must not be earlier than changes_scheduled_at or start_date. Note : This parameter can be backdated (set to a value in the past) only when the subscription is in cancelled or in_trial status. Do this to keep a record of when the trial ended in case it ended at some point in the past. When trial_end is backdated, the subscription immediately goes into active or non_renewing status. This parameter overrides the item_price_trial_period directly.

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.

Specifies the checkout layout that overrides the default checkout layout configured in the Checkout & Self-Serve Portal settings. . * in_app - Indicates in-app checkout version * full_page - Indicates full page checkout version

Possible values:

• "full_page"
• "in_app"

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.

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=<hosted_page_id>&state=cancelled
• This parameter is not applicable for iframe messaging and in-app checkout.

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.

Default value: false

Parameters for entity_identifiers

The unique id for the entity_identifier[i] in Chargebee. This is required when entity_identifier[operation][i] is update or delete.

The value of the entity_identifier. This identifies the customer entity on the Peppol network. For example: 10101010-STO-10.
Tip:

If there is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

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 is only one entity identifier for the customer and the value is the same as vat_number, then there is no need to provide the entity_identifiers[] array. See description for entity_identifiers[].

Parameters for subscription_items

The price/per unit price of the item. When not provided, the value set for the item price is used. This is only applicable when the pricing_model of the item price is flat_fee or per_unit. Also, it is only allowed when price overriding is enabled for the site. The value depends on the type of currency. If changes_scheduled_at is in the past and a unit_price is not passed, then the item price's current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.

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.

When price overriding is enabled for the site, the price or per-unit price of the item can be set here. The value set for the item price is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled. If changes_scheduled_at is in the past and a unit_price_in_decimal is not passed, then the item price's current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.

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

The quantity of the item purchased

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.

Not supported: This parameter is not supported in the API. If included in a request, it will be ignored.

The date/time when the trial period of the item ends. This applies to plan-items.

For the plan-item price:
the value determines the number of billing cycles the subscription runs before canceling automatically. If not provided, then the value set for the plan-item price is used.

For addon-item prices:
If addon billing cycles are enabled then this is the number of subscription billing cycles for which the addon is included. If not provided, then the value set under attached addons is used. Further, if that value is not provided, then the value set for the addon-item price is used.

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

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

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

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.

Default value: false

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

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.

Parameters for contract_term

Action to be taken when the contract term completes. * 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. * cancel - Contract term completes and subscription is canceled.

Possible values:

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

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

Default value: 0

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.

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

Parameters for card

The gateway account in which this payment source is stored.

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.

Default value: false

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

Parameters for customer

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.

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"

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.

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.

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.

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_generatedto verify a successful checkout.
• Redirect URL configured in Settings > Hosted Pages Settings would be overriden by this redirect URL.
• Eg : http://yoursite.com?id= <hosted_page_id>&state=succeeded
• This parameter is not applicable for iframe messaging.

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.

Possible values:

• "immediate"
• "delayed"

Parameters for item_tiers

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.

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.

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.

The overridden price of the tier. The value depends on the type of currency.

The highest value in the quantity tier.

The id of the item price for which the tier price is being overridden.

The lowest value in the quantity tier.

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.

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

Specifies the date or time when the subscription change will take effect after the quote is converted. * 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. * immediately - The change will be carried out immediately.

Possible values:

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