Settings
API Version
Product Catalog
Library

Hosted pages

Hosted pages are the easiest way to integrate Chargebee with your website. For card payment methods, they help meet most of your PCI DSS compliance requirements. Chargebee offers hosted pages where your customers can perform the following actions:

When you create a hosted page, it is available at a secure and unique URL. This URL can then be provided to your customer on your website or by other means such as email. On successful completion of the hosted page workflow by the customer, they are redirected to the redirect_url with the hosted page id and state passed as query string parameters. As soon as the redirection happens, retrieve the hosted page to get details of the customer, subscription, invoice etc.

Sample hosted page [ JSON ]

{ "created_at": 1517464663, "embed": false, "expires_at": 1517468263, "id": "__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu", "object": "hosted_page", "resource_version": 1517444863979, "state": "created", "type": "checkout_one_time", "updated_at": 1517444863, "url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu/" }

API Index URL GET

https://{site}.chargebee.com/api/v2/hosted_pages

Model Class

 

      Hosted page attributes
      
 
id
 

      optional, string, max chars=70
 Unique identifier generated for each hosted page requested. 
 
 
type
 

      optional, enumerated string
 Type of the requested hosted page. 
 
Possible values are
 
checkout_newCheckout new Subscriptioncheckout_existingCheckout existing Subscriptionupdate_payment_methodUpdate Payment Method for a Customermanage_payment_sourcesManage Payments for a customercollect_nowCollect Unpaid Invoices for a Customerextend_subscriptionTo extend a Subscription periodcheckout_one_timeCheckout one timepre_cancelThis hosted page is used to help retain customers when they attempt to cancel their account or subscription.view_voucherView Details of a voucher
 
checkout_newCheckout new Subscriptioncheckout_existingCheckout existing Subscriptionupdate_payment_methodUpdate Payment Method for a Customermanage_payment_sourcesManage Payments for a customer
 
collect_nowCollect Unpaid Invoices for a Customerextend_subscriptionTo extend a Subscription periodcheckout_one_timeCheckout one timepre_cancelThis hosted page is used to help retain customers when they attempt to cancel their account or subscription.view_voucherView Details of a voucher
 Show all values[+]
 
url
 

      optional, string, max chars=250
 Unique URL for the hosted page that will be included in your website. 
 
 
state
 

      optional, enumerated string, default=created
 Indicating the current state of the hosted page resource. 
 
Possible values are
 
createdIndicates the hosted page is just created.requestedIndicates the hosted page is requested by the websitesucceededIndicates the hosted page is successfully submitted by the user and response is sent to the return url.cancelledIndicates the page is cancelled by the end user after requesting it.acknowledgedIndicates the succeeded hosted page is acknowledged.
 
createdIndicates the hosted page is just created.requestedIndicates the hosted page is requested by the websitesucceededIndicates the hosted page is successfully submitted by the user and response is sent to the return url.cancelledIndicates the page is cancelled by the end user after requesting it.
 
acknowledgedIndicates the succeeded hosted page is acknowledged.
 Show all values[+]
 
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. 
 
 
 
created_at
 

      optional, timestamp(UTC) in seconds
 Indicates when this hosted page url is generated. 
 
 
expires_at
 

      optional, timestamp(UTC) in seconds
 Indicates when this hosted page url will expire. After this, the hosted page cannot be accessed. 
 
 
content
 

      jsonobject
 This attribute will be returned only during retrieve hosted page API call and also the retrieved hosted page resource state should be either in "succeeded" or "cancelled" state.
If hosted page state is "succeeded", then the subscription, customer, card & invoice(optional) resources during checkout can be obtained. 
If hosted page is state is "cancelled", then it will be empty i.e no information about checkout. 
 
 
updated_at
 

      optional, timestamp(UTC) in seconds
 Timestamp indicating when this hosted page was last updated. 
 
 
resource_version
 

      optional, long
 The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds. 
 
 
checkout_info
 

      optional, jsonobject
 Customer Info (email, first name and last name) given in the checkout page used for tracking abandoned carts.
Learn more 
 
 
business_entity_id
 

      optional, string, max chars=50
 The unique ID of the business entity of this hosted_page.  
 
 
 
 
id id
 

          optional, string, max chars=70
 Unique identifier generated for each hosted page requested. 
 
type type
 

          optional, enumerated string
 Type of the requested hosted page. 
 
Possible values are
 
checkout_newCheckout new Subscriptioncheckout_existingCheckout existing Subscriptionupdate_payment_methodUpdate Payment Method for a Customermanage_payment_sourcesManage Payments for a customercollect_nowCollect Unpaid Invoices for a Customerextend_subscriptionTo extend a Subscription periodcheckout_one_timeCheckout one timepre_cancelThis hosted page is used to help retain customers when they attempt to cancel their account or subscription.view_voucherView Details of a voucher
 
checkout_newCheckout new Subscriptioncheckout_existingCheckout existing Subscriptionupdate_payment_methodUpdate Payment Method for a Customermanage_payment_sourcesManage Payments for a customer
 
collect_nowCollect Unpaid Invoices for a Customerextend_subscriptionTo extend a Subscription periodcheckout_one_timeCheckout one timepre_cancelThis hosted page is used to help retain customers when they attempt to cancel their account or subscription.view_voucherView Details of a voucher
 Show all values[+]
url url
 

          optional, string, max chars=250
 Unique URL for the hosted page that will be included in your website. 
 
state state
 

          optional, enumerated string, default=created
 Indicating the current state of the hosted page resource. 
 
Possible values are
 
createdIndicates the hosted page is just created.requestedIndicates the hosted page is requested by the websitesucceededIndicates the hosted page is successfully submitted by the user and response is sent to the return url.cancelledIndicates the page is cancelled by the end user after requesting it.acknowledgedIndicates the succeeded hosted page is acknowledged.
 
createdIndicates the hosted page is just created.requestedIndicates the hosted page is requested by the websitesucceededIndicates the hosted page is successfully submitted by the user and response is sent to the return url.cancelledIndicates the page is cancelled by the end user after requesting it.
 
acknowledgedIndicates the succeeded hosted page is acknowledged.
 Show all values[+]
pass_thru_content 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. 
 
 
created_at created_at
 

          optional, timestamp(UTC) in seconds
 Indicates when this hosted page url is generated. 
 
expires_at expires_at
 

          optional, timestamp(UTC) in seconds
 Indicates when this hosted page url will expire. After this, the hosted page cannot be accessed. 
 
content 
 

          jsonobject
 This attribute will be returned only during retrieve hosted page API call and also the retrieved hosted page resource state should be either in "succeeded" or "cancelled" state.
If hosted page state is "succeeded", then the subscription, customer, card & invoice(optional) resources during checkout can be obtained. 
If hosted page is state is "cancelled", then it will be empty i.e no information about checkout. 
 
updated_at updated_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this hosted page was last updated. 
 
resource_version resource_version
 

          optional, long
 The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds. 
 
checkout_info 
 

          optional, jsonobject
 Customer Info (email, first name and last name) given in the checkout page used for tracking abandoned carts.
Learn more 
 
business_entity_id business_entity_id
 

          optional, string, max chars=50
 The unique ID of the business entity of this hosted_page.  
 
 
 
Consent Fields for Hosted page
 
 
Custom Fields for Hosted page
 
 

      Checkout charge-items and one-time charges
      
 
Idempotency Supported
 
 
Create a Chargebee hosted page to accept payment details from a customer and checkout charge-items and one-time charges.
 

The following steps describe how best to use this API:
 

     
 
  1. Call this endpoint, providing item prices, charges, coupons and a host of other details such as billing and shipping addresses of the customer, to be prefilled 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. 
    2.  
 
  2. Send the customer to the Checkout url received in the response.
    3.  
 
  3. Once they complete checkout, the set of charge-items and one-time charges are automatically invoiced against the respective customer record in Chargebee, and they are redirected to the redirect_url with the id and state attributes passed as query string parameters. 
    4.  
 
  4. Retrieve the hosted page at this stage to get the invoice details. 
    5.  

 

Customer resource lookup and creation
 

 When customer[id] is provided for this operation, it is looked up by Chargebee, and if found, the hosted_page is created for it. If not found, a new customer resource is created with an autogenarated ID, and the hosted_page is created. 
 

Multiple business entities
 

 If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context , and if not found, the resource is created for the default business entity of the site. 
  
Notes
 
 

      Sample Request
    
 
 
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time_for_items \
     -u {site_api_key}:\
     -d "customer[id]"="__test__XpbXKKYSOUtL5p2E" \
     -d "shipping_address[first_name]"="John" \
     -d "shipping_address[last_name]"="Mathew" \
     -d "shipping_address[city]"="Walnut" \
     -d "shipping_address[state]"="California" \
     -d "shipping_address[zip]"="91789" \
     -d "shipping_address[country]"="US" \
     -d "item_prices[item_price_id][0]"="ssl-charge-USD" \
     -d "item_prices[unit_price][0]"=2000 
 

      copy
      
Click to Copy
 
Creates a checkout with non-recurring addon for a customer.
 
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time_for_items \
     -u {site_api_key}:\
     -d "customer[id]"="__test__XpbXKKYSOUtL5p2E" \
     -d "shipping_address[first_name]"="John" \
     -d "shipping_address[last_name]"="Mathew" \
     -d "shipping_address[city]"="Walnut" \
     -d "shipping_address[state]"="California" \
     -d "shipping_address[zip]"="91789" \
     -d "shipping_address[country]"="US" \
     -d "item_prices[item_price_id][0]"="ssl-charge-USD" \
     -d "item_prices[unit_price][0]"=2000 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "hosted_page": {
        "created_at": 1517464663,
        "embed": false,
        "expires_at": 1517468263,
        "id": "__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu",
        "object": "hosted_page",
        "resource_version": 1517444863979,
        "state": "created",
        "type": "checkout_one_time",
        "updated_at": 1517444863,
        "url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu/"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time_for_items
    
 
Method
 
 
Input Parameters
 
  
 
business_entity_id[]
 

      optional, string, max chars=50 
 
Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.


 Note

An alternative way of passing this parameter is by means of a custom HTTP header.
 


 See also

Customer resource lookup and creation.
 
  
 
layout[]
 

      optional, enumerated string 
 Specifies the checkout layout that overrides the default checkout layout configured in the Checkout & Self-Serve Portal settings. . 
Possible values are
 
in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
 
in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
 
 Show all values[+]
 
invoice_note[]
 

      optional, string, max chars=2000 
 A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer. 
 
coupon_ids[[0..n]][0..n]
 

      optional, list of string 
 List of Coupons to be added. 
 
currency_code[]
 

      required if Multicurrency is enabled, string, max chars=3 
 The currency code (ISO 4217 format) of the invoice amount. 
 
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=<hosted_page_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=<hosted_page_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. 
 
 
 
 
 
 
customer[id]
 
optional, string, max chars=50 
 
The unique ID of the customer for which this hosted_page should be created. If not provided, the ID of the newly created customer resource is autogenerated.


 See also

Customer resource lookup and creation.
 
customer[email]
 
optional, string, max chars=70 
 Email of the customer. Configured email notifications will be sent to this email. 
customer[first_name]
 
optional, string, max chars=150 
 First name of the customer. If not provided  it will be got from contact information entered in the hosted page  
customer[last_name]
 
optional, string, max chars=150 
 Last name of the customer. If not provided  it will be got from contact information entered in the hosted page  
customer[company]
 
optional, string, max chars=250 
 Company name of the customer. 
customer[phone]
 
optional, string, max chars=50 
 Phone number of the customer 
customer[locale]
 
optional, string, max chars=50 
 Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication. 
customer[taxability]
 
optional, enumerated string, default=taxable 
 Specifies if the customer is liable for tax 
Possible values are
 
taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
 
taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
 
 Show all values[+]
customer[vat_number]
 
optional, string, max chars=20 
 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[vat_number_prefix]
 
optional, string, max chars=10 
 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[einvoicing_method]
 
optional, enumerated string 
 Determines whether to send einvoice manually or automatic. 
Possible values are
 
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
 
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
 
 Show all values[+]
customer[is_einvoice_enabled]
 
optional, boolean 
 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[entity_identifier_scheme]
 
optional, string, max chars=50 
 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[entity_identifier_standard]
 
optional, string, default=iso6523-actorid-upis, max chars=50 
 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.
    



 
customer[consolidated_invoicing]
 
optional, boolean 
 
Indicates whether invoices raised on the same day for the customer are consolidated. When provided, this overrides the default configuration at the site-level. This parameter can be provided only when Consolidated Invoicing is enabled.



    
Note:

    
Any invoices raised when a subscription activates from in_trial or future status, are not consolidated by default. Contact Support to enable consolidation for such invoices.


 
 
 
invoice[po_number]
 
optional, string, max chars=100 
 Purchase Order Number for this invoice. 
 
 
card[gateway_account_id]
 
optional, string, max chars=50 
 The gateway account in which this payment source is stored. 
 
 
billing_address[first_name]
 
optional, string, max chars=150 
 The first name of the billing contact. 
billing_address[last_name]
 
optional, string, max chars=150 
 The last name of the billing contact. 
billing_address[email]
 
optional, string, max chars=70 
 The email address. 
billing_address[company]
 
optional, string, max chars=250 
 The company name. 
billing_address[phone]
 
optional, string, max chars=50 
 The phone number. 
billing_address[line1]
 
optional, string, max chars=150 
 Address line 1 
billing_address[line2]
 
optional, string, max chars=150 
 Address line 2 
billing_address[line3]
 
optional, string, max chars=150 
 Address line 3 
billing_address[city]
 
optional, string, max chars=50 
 The name of the city. 
billing_address[state_code]
 
optional, string, max chars=50 
 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[state]
 
optional, string, max chars=50 
 The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided. 
billing_address[zip]
 
optional, string, max chars=20 
 Zip or postal code. The number of characters is validated according to the rules specified here. 
billing_address[country]
 
optional, string, max chars=50 
 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.
    


 
billing_address[validation_status]
 
optional, enumerated string, default=not_validated 
 The address verification status. 
Possible values are
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
 Show all values[+]
 
 
shipping_address[first_name]
 
optional, string, max chars=150 
 The first name of the contact. 
shipping_address[last_name]
 
optional, string, max chars=150 
 The last name of the contact. 
shipping_address[email]
 
optional, string, max chars=70 
 The email address. 
shipping_address[company]
 
optional, string, max chars=250 
 The company name. 
shipping_address[phone]
 
optional, string, max chars=50 
 The phone number. 
shipping_address[line1]
 
optional, string, max chars=150 
 Address line 1 
shipping_address[line2]
 
optional, string, max chars=150 
 Address line 2 
shipping_address[line3]
 
optional, string, max chars=150 
 Address line 3 
shipping_address[city]
 
optional, string, max chars=50 
 The name of the city. 
shipping_address[state_code]
 
optional, string, max chars=50 
 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[state]
 
optional, string, max chars=50 
 The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided. 
shipping_address[zip]
 
optional, string, max chars=20 
 Zip or postal code. The number of characters is validated according to the rules specified here. 
shipping_address[country]
 
optional, string, max chars=50 
 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.
    


 
shipping_address[validation_status]
 
optional, enumerated string, default=not_validated 
 The address verification status. 
Possible values are
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
 Show all values[+]
 
 
item_prices[item_price_id][0..n]
 
optional, string, max chars=100 
 A unique ID for your system to identify the item price. 
item_prices[quantity][0..n]
 
optional, integer, min=1 
 Item price quantity 
item_prices[quantity_in_decimal][0..n]
 
optional, string, max chars=33 
 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. 
item_prices[unit_price][0..n]
 
optional, in cents, min=0 
 The price or per-unit-price of the item price. By default, it is the value set for the item_price. This is only applicable when the pricing_model of the item_price is flat_fee or per_unit. The value depends on the type of currency. 
item_prices[unit_price_in_decimal][0..n]
 
optional, string, max chars=39 
 The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled. 
item_prices[date_from][0..n]
 
optional, timestamp(UTC) in seconds 
 The time when the service period for the item starts. 
item_prices[date_to][0..n]
 
optional, timestamp(UTC) in seconds 
 The time when the service period for the item ends. 
 
 
item_tiers[item_price_id][0..n]
 
optional, string, max chars=100 
 The id of the item price to which this tier belongs. 
item_tiers[starting_unit][0..n]
 
optional, integer, min=1 
 The lowest value in the quantity tier. 
item_tiers[ending_unit][0..n]
 
optional, integer 
 The highest value in the quantity tier. 
item_tiers[price][0..n]
 
optional, in cents, default=0, min=0 
 The per-unit price for the tier when the pricing_model is tiered or volume. The total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency. 
item_tiers[starting_unit_in_decimal][0..n]
 
optional, string, max chars=33 
 The decimal representation of the 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[ending_unit_in_decimal][0..n]
 
optional, string, max chars=33 
 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. 
item_tiers[price_in_decimal][0..n]
 
optional, string, max chars=39 
 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[pricing_type][0..n]
 
optional, enumerated string 
 Pricing type for the tier. 
Possible values are
 
per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
 
per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
 
 Show all values[+]
item_tiers[package_size][0..n]
 
optional, integer, min=1 
 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. 
 
 
charges[amount][0..n]
 
optional, in cents, min=1 
 The amount to be charged. The unit depends on the type of currency. 
charges[amount_in_decimal][0..n]
 
optional, string, max chars=39 
 The decimal representation of the amount for the one-time charge. Provide the value in major units of the currency. Can be provided only when multi-decimal pricing is enabled. 
charges[description][0..n]
 
optional, string, max chars=250 
 Description for this charge 
charges[taxable][0..n]
 
optional, boolean, default=true 
 The amount to be charged is taxable or not. 
charges[tax_profile_id][0..n]
 
optional, string, max chars=50 
 Tax profile of the charge. 
charges[avalara_tax_code][0..n]
 
optional, string, max chars=50 
 The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration. 
charges[hsn_code][0..n]
 
optional, string, max chars=50 
 The HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
 
charges[taxjar_product_code][0..n]
 
optional, string, max chars=50 
 The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration. 
charges[avalara_sale_type][0..n]
 
optional, enumerated string 
 Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration. 
Possible values are
 
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
 
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
 
 Show all values[+]
charges[avalara_transaction_type][0..n]
 
optional, integer 
 Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration. 
charges[avalara_service_type][0..n]
 
optional, integer 
 Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration. 
charges[date_from][0..n]
 
optional, timestamp(UTC) in seconds 
 The time when the service period for the charge starts. 
charges[date_to][0..n]
 
optional, timestamp(UTC) in seconds 
 The time when the service period for the charge ends. 
charges[discount_amount][0..n]
 
optional, in cents, min=0 
 The value of the discount. The format of this value depends on the kind of currency. Either this parameter or charges[discount_percentage] should be passed.  
charges[discount_percentage][0..n]
 
optional, double, min=0.01, max=100.0 
 The percentage of the original amount that should be deducted from it. Either this parameter or charges[discount_amount] should be passed.  
 
 
discounts[percentage][0..n]
 
optional, double, min=0.01, max=100.0 
 The percentage of the original amount that should be deducted from it.  
discounts[amount][0..n]
 
optional, in cents, min=0 
 The value of the discount. The format of this value depends on the kind of currency.  
discounts[apply_on][0..n]
 
required, enumerated string 
 The amount on the invoice to which the discount is applied.  
Possible values are
 
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
 
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
 
 Show all values[+]
discounts[item_price_id][0..n]
 
optional, string, max chars=100 
 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.  
 
 
entity_identifiers[id][0..n]
 
optional, string, max chars=40 
 The unique id for the entity_identifier[i] in Chargebee. This is required when entity_identifier[operation][i] is update or delete.
 
entity_identifiers[scheme][0..n]
 
optional, string, max chars=50 
 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[].
    



 
entity_identifiers[value][0..n]
 
optional, string, max chars=50 
 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[].
    



 
entity_identifiers[operation][0..n]
 
optional, enumerated string 
 The operation to be performed for the entity_identifier.
 
Possible values are
 
createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
 
createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
 
 Show all values[+]
entity_identifiers[standard][0..n]
 
optional, string, default=iso6523-actorid-upis, max chars=50 
 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[].
    


 
   
 
Returns
 
hosted_page  hosted_page
 

      always returned 
 Resource object representing hosted_page
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    

      Create checkout for a new subscription
      
 
Idempotency Supported
 
 
 Create a Chargebee hosted page to accept payment details from a customer and checkout a new subscription. 
 
 The following steps describe how best to use this API: 
 
     
  1.  
    Call this endpoint, providing 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.
     
    2.  
  2.  Send the customer to the Checkout url received in the response. 
    3.  
  3.  Once they complete checkout, a new subscription is automatically created 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. 
    4.  
  4.  Retrieve the hosted page at this stage to get the subscription and invoice details. 
    5.  
 
 
Customer resource lookup and creation
 
 When the customer[id] parameter is provided and if a customer resource with the ID is found to be already created in Chargebee, the subscription is created under that customer resource. If not found, then a new customer resource is created with an autogenarated ID and the subscription is created under it. 
 
Multiple business entities
 
 If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site. 
  
Notes
 
 

      Sample Request
    
 
 
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new_for_items \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=1 \
     -d "subscription_items[item_price_id][1]"="day-pass-USD" \
     -d "subscription_items[unit_price][1]"=100 
 

      copy
      
Click to Copy
 
Checkout a new subscription for items
 
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new_for_items \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=1 \
     -d "subscription_items[item_price_id][1]"="day-pass-USD" \
     -d "subscription_items[unit_price][1]"=100 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "hosted_page": {
        "created_at": 1517478505,
        "embed": false,
        "expires_at": 1517482105,
        "id": "__test__bmJkuEShKUEFomgKJsKvpKvKZpcueGpH1",
        "object": "hosted_page",
        "resource_version": 1517478505000,
        "state": "created",
        "type": "checkout_new",
        "updated_at": 1517478505,
        "url": "https://yourapp.chargebee.com/pages/v3/__test__bmJkuEShKUEFomgKJsKvpKvKZpcueGpH1/"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new_for_items
    
 
Method
 
 
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 values are
 
in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
 
in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
 
 Show all values[+]
 
business_entity_id[]
 

      optional, string, max chars=50 
 
Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.


 Note

An alternative way of passing this parameter is by means of a custom HTTP header.
 


 See also

Customer resource lookup and creation.
 
  
 
billing_cycles[]
 

      optional, integer, min=0 
 The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan-item price is used. 
 
mandatory_items_to_remove[[0..n]][0..n]
 

      optional, list of string 
 Item ids of mandatorily attached addons that are to be removed from the subscription. 
 
terms_to_charge[]
 

      optional, integer, min=1 
 The number of subscription billing cycles (including the first one) to invoice in advance. 
 
billing_alignment_mode[]
 

      optional, enumerated string 
 Override the  billing alignment mode for Calendar Billing. Only applicable when using Calendar Billing. The default value is that which has been configured for the site. 
Possible values are
 
immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
 
immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
 
 Show all values[+]
 
coupon_ids[[0..n]][0..n]
 

      optional, list of string 
 List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes. 
 
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=<hosted_page_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=<hosted_page_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[id]
 
optional, string, max chars=50 
 A unique and immutable identifier for a new subscription. If not provided, it is autogenerated. 
subscription[trial_end]
 
optional, timestamp(UTC) in seconds 
 End of the trial period for the subscription. This overrides the trial period set for the plan-item. The value must be later than start_date. Set it to 0 to have no trial period. This parameter overrides the item_price_trial_period directly. 
subscription[start_date]
 
optional, timestamp(UTC) in seconds 
 The date/time at which the subscription is to start. If not provided, the subscription starts immediately. You can provide a value in the past as well. This is called backdating the subscription creation and is done when the subscription has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:

    
    
  • Backdating is enabled for subscription creation operations.
    • 
    
  • The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
    • 
    
  • 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, start_date cannot be earlier than 14th February.
    • 

 
subscription[coupon]
 
optional, string, max chars=100 
 
 The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response. 
 

     
 
  • resource_not_found : Returned if the coupon is not present.
    •  
 
  • resource_limit_exhausted : Returned if the coupon has expired or the maximum redemption for the coupon has already been reached. 
    •  
 
  • invalid_request : Returned if the coupon is not applicable for the particular plan/addon. 
    •  

 
subscription[auto_collection]
 
optional, enumerated string 
 Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property. 
Possible values are
 
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
 
onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
 
 Show all values[+]
subscription[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. 
subscription[po_number]
 
optional, string, max chars=100 
 Purchase order number for this subscription. 
subscription[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. 
 
 
customer[id]
 
optional, string, max chars=50 
 
 The unique identifier for the customer resource for which the subscription should be created. 
 
 See also 
 Customer resource lookup and creation. 
 
 When not provided, a new customer is created with the ID set to the value provided for subscription[id]. If subscription[id] is unavailable, then the customer ID is autogenerated. 
 
customer[email]
 
optional, string, max chars=70 
 Email of the customer. Configured email notifications will be sent to this email. 
customer[first_name]
 
optional, string, max chars=150 
 First name of the customer. If not provided  it will be got from contact information entered in the hosted page  
customer[last_name]
 
optional, string, max chars=150 
 Last name of the customer. If not provided  it will be got from contact information entered in the hosted page  
customer[company]
 
optional, string, max chars=250 
 Company name of the customer. 
customer[phone]
 
optional, string, max chars=50 
 Phone number of the customer 
customer[locale]
 
optional, string, max chars=50 
 Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication. 
customer[taxability]
 
optional, enumerated string, default=taxable 
 Specifies if the customer is liable for tax 
Possible values are
 
taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
 
taxableComputes tax for the customer based on the site configuration. In some cases, depending on the region, shipping_address is needed. If not provided, then billing_address is used to compute tax. If that’s not available either, the tax is taken as zero.exempt
  • Customer is exempted from tax. When using Chargebee’s native Taxes feature or when using the TaxJar integration, no other action is needed.
  • However, when using our Avalara integration, optionally, specify entity_code or exempt_number attributes if you use Chargebee’s AvaTax for Sales or specify exemption_details attribute if you use Chargebee’s AvaTax for Communications integration. Tax may still be applied by Avalara for certain values of entity_code/exempt_number/exemption_details based on the state/region/province of the taxable address.
 
 Show all values[+]
customer[vat_number]
 
optional, string, max chars=20 
 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[vat_number_prefix]
 
optional, string, max chars=10 
 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[is_einvoice_enabled]
 
optional, boolean 
 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[entity_identifier_scheme]
 
optional, string, max chars=50 
 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[entity_identifier_standard]
 
optional, string, default=iso6523-actorid-upis, max chars=50 
 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.
    



 
customer[einvoicing_method]
 
optional, enumerated string 
 Determines whether to send einvoice manually or automatic. 
Possible values are
 
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
 
automaticUse this value to send e-invoice every time an invoice or credit note is created.manualWhen manual is selected the automatic e-invoice sending is disabled. Use this value to send e-invoice manually through UI or API.site_defaultThe default value of the site which can be overridden at the customer level.
 
 Show all values[+]
 
 
card[gateway_account_id]
 
optional, string, max chars=50 
 The gateway account in which this payment source is stored. 
 
 
billing_address[first_name]
 
optional, string, max chars=150 
 The first name of the billing contact. 
billing_address[last_name]
 
optional, string, max chars=150 
 The last name of the billing contact. 
billing_address[email]
 
optional, string, max chars=70 
 The email address. 
billing_address[company]
 
optional, string, max chars=250 
 The company name. 
billing_address[phone]
 
optional, string, max chars=50 
 The phone number. 
billing_address[line1]
 
optional, string, max chars=150 
 Address line 1 
billing_address[line2]
 
optional, string, max chars=150 
 Address line 2 
billing_address[line3]
 
optional, string, max chars=150 
 Address line 3 
billing_address[city]
 
optional, string, max chars=50 
 The name of the city. 
billing_address[state_code]
 
optional, string, max chars=50 
 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[state]
 
optional, string, max chars=50 
 The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided. 
billing_address[zip]
 
optional, string, max chars=20 
 Zip or postal code. The number of characters is validated according to the rules specified here. 
billing_address[country]
 
optional, string, max chars=50 
 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.
    


 
billing_address[validation_status]
 
optional, enumerated string, default=not_validated 
 The address verification status. 
Possible values are
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
 Show all values[+]
 
 
shipping_address[first_name]
 
optional, string, max chars=150 
 The first name of the contact. 
shipping_address[last_name]
 
optional, string, max chars=150 
 The last name of the contact. 
shipping_address[email]
 
optional, string, max chars=70 
 The email address. 
shipping_address[company]
 
optional, string, max chars=250 
 The company name. 
shipping_address[phone]
 
optional, string, max chars=50 
 The phone number. 
shipping_address[line1]
 
optional, string, max chars=150 
 Address line 1 
shipping_address[line2]
 
optional, string, max chars=150 
 Address line 2 
shipping_address[line3]
 
optional, string, max chars=150 
 Address line 3 
shipping_address[city]
 
optional, string, max chars=50 
 The name of the city. 
shipping_address[state_code]
 
optional, string, max chars=50 
 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[state]
 
optional, string, max chars=50 
 The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided. 
shipping_address[zip]
 
optional, string, max chars=20 
 Zip or postal code. The number of characters is validated according to the rules specified here. 
shipping_address[country]
 
optional, string, max chars=50 
 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.
    


 
shipping_address[validation_status]
 
optional, enumerated string, default=not_validated 
 The address verification status. 
Possible values are
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
 
 Show all values[+]
 
 
contract_term[action_at_term_end]
 
optional, enumerated string 
 Action to be taken when the contract term completes. 
Possible values are
 
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.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
     
    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.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
     
     Show all values[+]
    contract_term[cancellation_cutoff_period]
     
    optional, integer, default=0 
     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 
     
     
    subscription_items[item_price_id][0..n]
     
    required, string, max chars=100 
     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. 
    subscription_items[quantity][0..n]
     
    optional, integer, min=1 
     The quantity of the item purchased 
    subscription_items[quantity_in_decimal][0..n]
     
    optional, string, max chars=33 
     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. 
    subscription_items[unit_price][0..n]
     
    optional, in cents, min=0 
     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. 
    subscription_items[unit_price_in_decimal][0..n]
     
    optional, string, max chars=39 
     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. 
    subscription_items[billing_cycles][0..n]
     
    optional, integer, min=0 
     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.     
    subscription_items[trial_end][0..n]
     
    optional, timestamp(UTC) in seconds 
     The date/time when the trial period of the item ends. This applies to plan-items. 
    subscription_items[service_period_days][0..n]
     
    optional, integer, min=1, max=730 
     Not supported: This parameter is not supported in the API. If included in a request, it will be ignored. 
    subscription_items[charge_on_event][0..n]
     
    optional, enumerated string 
     When charge_on_option option is set to on_event, this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items. 
    Possible values are
     
    subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.contract_terminationwhen a contract term is terminated.
     
    subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.
     
    contract_terminationwhen a contract term is terminated.
     Show all values[+]
    subscription_items[charge_once][0..n]
     
    optional, boolean 
     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[charge_on_option][0..n]
     
    optional, enumerated string 
     Indicates when the charge-item is to be charged. This parameter only applies to charge-items. 
    Possible values are
     
    immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
     
    immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
     
     Show all values[+]
     
     
    discounts[apply_on][0..n]
     
    required, enumerated string 
     The amount on the invoice to which the discount is applied.  
    Possible values are
     
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
     
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
     
     Show all values[+]
    discounts[duration_type][0..n]
     
    required, enumerated string, default=forever 
     Specifies the time duration for which this discount is attached to the subscription.  
    Possible values are
     
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
     
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
     
     Show all values[+]
    discounts[percentage][0..n]
     
    optional, double, min=0.01, max=100.0 
     The percentage of the original amount that should be deducted from it.  
    discounts[amount][0..n]
     
    optional, in cents, min=0 
     The value of the discount. The format of this value depends on the kind of currency.  
    discounts[period][0..n]
     
    optional, integer, min=1 
     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[period_unit][0..n]
     
    optional, enumerated string 
     The unit of time for period. Applicable only when duration_type is limited_period.  
    Possible values are
     
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
     
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
     
     Show all values[+]
    discounts[included_in_mrr][0..n]
     
    optional, boolean 
     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[item_price_id][0..n]
     
    optional, string, max chars=100 
     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.  
     
     
    item_tiers[item_price_id][0..n]
     
    optional, string, max chars=100 
     The id of the item price for which the tier price is being overridden. 
    item_tiers[starting_unit][0..n]
     
    optional, integer, min=1 
     The lowest value in the quantity tier. 
    item_tiers[ending_unit][0..n]
     
    optional, integer 
     The highest value in the quantity tier. 
    item_tiers[price][0..n]
     
    optional, in cents, default=0, min=0 
     The overridden price of the tier. The value depends on the type of currency. 
    item_tiers[starting_unit_in_decimal][0..n]
     
    optional, string, max chars=33 
     The decimal representation of the 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[ending_unit_in_decimal][0..n]
     
    optional, string, max chars=33 
     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. 
    item_tiers[price_in_decimal][0..n]
     
    optional, string, max chars=39 
     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[pricing_type][0..n]
     
    optional, enumerated string 
     Pricing type for the tier. 
    Possible values are
     
    per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
     
    per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
     
     Show all values[+]
    item_tiers[package_size][0..n]
     
    optional, integer, min=1 
     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. 
     
     
    entity_identifiers[id][0..n]
     
    optional, string, max chars=40 
     The unique id for the entity_identifier[i] in Chargebee. This is required when entity_identifier[operation][i] is update or delete.
 
    entity_identifiers[scheme][0..n]
     
    optional, string, max chars=50 
     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[].
    
    

    
     
    entity_identifiers[value][0..n]
     
    optional, string, max chars=50 
     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[].
    
    

    
     
    entity_identifiers[operation][0..n]
     
    optional, enumerated string 
     The operation to be performed for the entity_identifier.
 
    Possible values are
     
    createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
     
    createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
     
     Show all values[+]
    entity_identifiers[standard][0..n]
     
    optional, string, default=iso6523-actorid-upis, max chars=50 
     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[].
    
    

     
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Create checkout to update a subscription
      
     
    Idempotency Supported
     
     
     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: 
     

       
 
    1. 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.
      2.  
 
    2.  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. 
      3.  
 
    3.  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. 
      4.  
 
    4.  Retrieve the hosted page at this stage to get the subscription and invoice details. 
      5.  

     

      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing_for_items \
     -u {site_api_key}:\
     -d "subscription[id]"="__test__KyVnGWS4EgP3HA" \
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=4 \
     -d "subscription_items[unit_price][0]"=1000 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing_for_items \
     -u {site_api_key}:\
     -d "subscription[id]"="__test__KyVnGWS4EgP3HA" \
     -d "subscription_items[item_price_id][0]"="basic-USD" \
     -d "subscription_items[quantity][0]"=4 \
     -d "subscription_items[unit_price][0]"=1000 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517478504,
        "embed": false,
        "expires_at": 1517482104,
        "id": "__test__lxYzKMHM7UcueYo6mZabybQOacdfXv7LtV",
        "object": "hosted_page",
        "resource_version": 1517478504000,
        "state": "created",
        "type": "checkout_existing",
        "updated_at": 1517478504,
        "url": "https://yourapp.chargebee.com/pages/v3/__test__lxYzKMHM7UcueYo6mZabybQOacdfXv7LtV/"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing_for_items
    
     
    Method
     
     
    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 values are
     
    in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
     
    in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
     
     Show all values[+]
     
    mandatory_items_to_remove[[0..n]][0..n]
     
    
      optional, list of 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 values are
     
    immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
     
    immediateSubscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..delayedSubscription period will be aligned with the configured billing date at the next renewal.
     
     Show all values[+]
     
    coupon_ids[[0..n]][0..n]
     
    
      optional, list of 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.
     
     
     
    change_option[]
     
    
      optional, enumerated string 
     Specifies the date or time when the subscription change will take effect after the quote is converted. 
    Possible values are
     
    immediatelyThe change will be carried out immediately.end_of_termThe change will be carried out at the end of the current billing cycle of the subscriptionspecific_dateThe change will be carried out on the date specified under changes_scheduled_at.
     
    immediatelyThe change will be carried out immediately.end_of_termThe change will be carried out at the end of the current billing cycle of the subscriptionspecific_dateThe change will be carried out on the date specified under changes_scheduled_at.
     
     Show all values[+]
     
    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.
    .     
     
    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=<hosted_page_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=<hosted_page_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[id]
     
    required, string, max chars=50 
     A unique and immutable identifier for the subscription. If not provided, it is autogenerated. 
    subscription[start_date]
     
    optional, timestamp(UTC) in seconds 
     The new start date of a future subscription. Applicable only for future subscriptions. 
    subscription[trial_end]
     
    optional, timestamp(UTC) in seconds 
     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. 
    subscription[auto_collection]
     
    optional, enumerated string 
     Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property. 
    Possible values are
     
    onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
     
    onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic collection of charges will not be made for this subscription. Use this for offline payments.
     
     Show all values[+]
    subscription[offline_payment_method]
     
    optional, enumerated string 
     The preferred offline payment method for the subscription. 
    Possible values are
     
    no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transferach_creditACH Creditsepa_creditSEPA CreditboletoBoletous_automated_bank_transferUS Automated Bank Transfereu_automated_bank_transferEU Automated Bank Transferuk_automated_bank_transferUK Automated Bank Transferjp_automated_bank_transferJP Automated Bank Transfermx_automated_bank_transferMX Automated Bank TransfercustomCustom
     
    no_preferenceNo PreferencecashCashcheckCheckbank_transferBank Transfer
     
    ach_creditACH Creditsepa_creditSEPA CreditboletoBoletous_automated_bank_transferUS Automated Bank Transfereu_automated_bank_transferEU Automated Bank Transferuk_automated_bank_transferUK Automated Bank Transferjp_automated_bank_transferJP Automated Bank Transfermx_automated_bank_transferMX Automated Bank TransfercustomCustom
     Show all values[+]
    subscription[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. 
    subscription[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. 
     
     
    customer[vat_number]
     
    optional, string, max chars=20 
     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[vat_number_prefix]
     
    optional, string, max chars=10 
     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[is_einvoice_enabled]
     
    optional, boolean 
     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[entity_identifier_scheme]
     
    optional, string, max chars=50 
     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[entity_identifier_standard]
     
    optional, string, default=iso6523-actorid-upis, max chars=50 
     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.
    
    

    
     
     
     
    card[gateway_account_id]
     
    optional, string, max chars=50 
     The gateway account in which this payment source is stored. 
     
     
    contract_term[action_at_term_end]
     
    optional, enumerated string 
     Action to be taken when the contract term completes. 
    Possible values are
     
    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.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
     
    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.
    • evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.
     
     Show all values[+]
    contract_term[cancellation_cutoff_period]
     
    optional, integer, default=0 
     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 
     
     
    subscription_items[item_price_id][0..n]
     
    required, string, max chars=100 
     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. 
    subscription_items[quantity][0..n]
     
    optional, integer, min=1 
     The quantity of the item purchased 
    subscription_items[quantity_in_decimal][0..n]
     
    optional, string, max chars=33 
     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. 
    subscription_items[unit_price][0..n]
     
    optional, in cents, min=0 
     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. 
    subscription_items[unit_price_in_decimal][0..n]
     
    optional, string, max chars=39 
     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. 
    subscription_items[billing_cycles][0..n]
     
    optional, integer, min=0 
     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.     
    subscription_items[trial_end][0..n]
     
    optional, timestamp(UTC) in seconds 
     The date/time when the trial period of the item ends. This applies to plan-items. 
    subscription_items[service_period_days][0..n]
     
    optional, integer, min=1, max=730 
     Not supported: This parameter is not supported in the API. If included in a request, it will be ignored. 
    subscription_items[charge_on_event][0..n]
     
    optional, enumerated string 
     When charge_on_option option is set to on_event, this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items. 
    Possible values are
     
    subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.contract_terminationwhen a contract term is terminated.
     
    subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.
     
    contract_terminationwhen a contract term is terminated.
     Show all values[+]
    subscription_items[charge_once][0..n]
     
    optional, boolean 
     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[charge_on_option][0..n]
     
    optional, enumerated string 
     Indicates when the charge-item is to be charged. This parameter only applies to charge-items. 
    Possible values are
     
    immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
     
    immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
     
     Show all values[+]
     
     
    discounts[apply_on][0..n]
     
    required, enumerated string 
     The amount on the invoice to which the discount is applied.  
    Possible values are
     
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
     
    invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
     
     Show all values[+]
    discounts[duration_type][0..n]
     
    required, enumerated string, default=forever 
     Specifies the time duration for which this discount is attached to the subscription.  
    Possible values are
     
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
     
    one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
     
     Show all values[+]
    discounts[percentage][0..n]
     
    optional, double, min=0.01, max=100.0 
     The percentage of the original amount that should be deducted from it. 
    discounts[amount][0..n]
     
    optional, in cents, min=0 
     The value of the discount. The format of this value depends on the kind of currency.  
    discounts[period][0..n]
     
    optional, integer, min=1 
     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[period_unit][0..n]
     
    optional, enumerated string 
     The unit of time for period. Applicable only when duration_type is limited_period.  
    Possible values are
     
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
     
    dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
     
     Show all values[+]
    discounts[included_in_mrr][0..n]
     
    optional, boolean 
     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[item_price_id][0..n]
     
    optional, string, max chars=100 
     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[operation_type][0..n]
     
    required, enumerated string 
     The operation to be carried out for the discount.  
    Possible values are
     
    addThe discount is attached to the subscription.removeThe discount (given by discounts[id]) is removed from the subscription. Subsequent invoices will no longer have the discount applied. Tip: If you want to replace a discount, remove it and add another in the same API call.
     
    addThe discount is attached to the subscription.removeThe discount (given by discounts[id]) is removed from the subscription. Subsequent invoices will no longer have the discount applied. Tip: If you want to replace a discount, remove it and add another in the same API call.
     
     Show all values[+]
    discounts[id][0..n]
     
    optional, string, max chars=50 
     An immutable unique id for the discount. It is always auto-generated. 
     
     
    item_tiers[item_price_id][0..n]
     
    optional, string, max chars=100 
     The id of the item price for which the tier price is being overridden. 
    item_tiers[starting_unit][0..n]
     
    optional, integer, min=1 
     The lowest value in the quantity tier. 
    item_tiers[ending_unit][0..n]
     
    optional, integer 
     The highest value in the quantity tier. 
    item_tiers[price][0..n]
     
    optional, in cents, default=0, min=0 
     The overridden price of the tier. The value depends on the type of currency. 
    item_tiers[starting_unit_in_decimal][0..n]
     
    optional, string, max chars=33 
     The decimal representation of the 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[ending_unit_in_decimal][0..n]
     
    optional, string, max chars=33 
     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. 
    item_tiers[price_in_decimal][0..n]
     
    optional, string, max chars=39 
     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[pricing_type][0..n]
     
    optional, enumerated string 
     Pricing type for the tier. 
    Possible values are
     
    per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
     
    per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
     
     Show all values[+]
    item_tiers[package_size][0..n]
     
    optional, integer, min=1 
     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. 
     
     
    entity_identifiers[id][0..n]
     
    optional, string, max chars=40 
     The unique id for the entity_identifier[i] in Chargebee. This is required when entity_identifier[operation][i] is update or delete.
 
    entity_identifiers[scheme][0..n]
     
    optional, string, max chars=50 
     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[].
    
    

    
     
    entity_identifiers[value][0..n]
     
    optional, string, max chars=50 
     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[].
    
    

    
     
    entity_identifiers[operation][0..n]
     
    optional, enumerated string 
     The operation to be performed for the entity_identifier.
 
    Possible values are
     
    createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
     
    createCreates a new entity_identifier for the customer.updateUpdates an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.deleteDeletes an existing entity_identifier for the customer. entity_identifier[id] must be provided in this case.
     
     Show all values[+]
    entity_identifiers[standard][0..n]
     
    optional, string, default=iso6523-actorid-upis, max chars=50 
     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[].
    
    

     
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Update payment method
      
     
    Idempotency Supported
     
     
     Note: If you're using In-App Checkout , use Manage Payment Sources API to request your customers to update their payment method details or change their payment method. 
     

     Using this API, you can request your customers to update their payment method details or change their payment method. This is used in scenarios like customers updating their payment methods before the end of trial or customers switching among payment methods. 
     

     When this API is invoked, it returns a hosted page URL. When the customers are directed to this URL, they will be able to change/update their payment methods. 
     

     Depending on the payment methods (Card, PayPal Express Checkout, Amazon Payments) that you offer your customers, they will find options to switch among the various methods of payment. 
     Note: 

       
 
    •  If the card[gateway] parameter is passed, and the customer chooses Card as a payment method, then the card details are stored in the gateway which is passed. However, if the card[gateway] parameter is passed and the customer chooses PayPal Express Checkout/Amazon Payments as a payment method, the gateway passed will be ignored. 
      •  
 
    •  The option of embedding into an iframe is not supported for PayPal Express Checkout and Amazon Payments as customers are redirected to the respective website pages. Hence if you have PayPal Express Checkout/Amazon Payments configured and pass the parameter embed=true, this will result in an unsuccessful API request. Also, if you have all the three payment methods (Card, Paypal Express Checkout and Amazon Payments) configured and pass the parameter embed=true, the returned hosted page URL will show only Card Payment as a payment method. 
      •  

      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/update_payment_method \
     -u {site_api_key}:\
     -d "customer[id]"="__test__KyVnHhSBWmKhy2uX" \
     -d "card[gateway_account_id]"="gw___test__KyVnGlSBWmAIk2Ph" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/update_payment_method \
     -u {site_api_key}:\
     -d "customer[id]"="__test__KyVnHhSBWmKhy2uX" \
     -d "card[gateway_account_id]"="gw___test__KyVnGlSBWmAIk2Ph" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517506020,
        "embed": true,
        "expires_at": 1517592420,
        "id": "__test__Rvi8fL7SS0CURBeH2k0CgkPLH6MyU2Sy",
        "object": "hosted_page",
        "resource_version": 1517506020000,
        "state": "created",
        "type": "update_payment_method",
        "updated_at": 1517506020,
        "url": "https://yourapp.chargebee.com/pages/v2/__test__Rvi8fL7SS0CURBeH2k0CgkPLH6MyU2Sy/update_payment_method"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/update_payment_method
    
     
    Method
     
     
    Input Parameters
     
      
     
    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=<hosted_page_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=<hosted_page_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 session, 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. 
     
     
    iframe_messaging[]
     
    
      optional, boolean, default=false 
     If true then iframe will communicate with the parent window. Applicable only for embedded(iframe) hosted pages. If you're using iframe_messaging you need to implement onSuccess & onCancel callbacks.

    Note : This parameter is not applicable for in-app checkout.     
     
     
     
     
     
    customer[id]
     
    required, string, max chars=50 
     Identifier of the customer. 
     
     
    card[gateway_account_id]
     
    optional, string, max chars=50 
     The gateway account in which this payment source is stored. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Manage Payment Sources
      
     
    Idempotency Supported
     
     
    This API generates a hosted page URL to add new or update existing payment sources for the customer.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/manage_payment_sources \
     -u {site_api_key}:\
     -d "customer[id]"="__test__KyVnHhSBWmJIX2uE" \
     -d "card[gateway_account_id]"="gw___test__KyVnGlSBWmAIk2Ph" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/manage_payment_sources \
     -u {site_api_key}:\
     -d "customer[id]"="__test__KyVnHhSBWmJIX2uE" \
     -d "card[gateway_account_id]"="gw___test__KyVnGlSBWmAIk2Ph" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517506015,
        "embed": false,
        "expires_at": 1517592415,
        "id": "__test__LycuLPCkhW3axOiXjHWkOOVl3ZE3yLLni",
        "object": "hosted_page",
        "resource_version": 1517506015000,
        "state": "created",
        "type": "manage_payment_sources",
        "updated_at": 1517506015,
        "url": "https://yourapp.chargebee.com/pages/v3/__test__LycuLPCkhW3axOiXjHWkOOVl3ZE3yLLni/"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/manage_payment_sources
    
     
    Method
     
     
    Input Parameters
     
      
     
    redirect_url[]
     
    
      optional, string, max chars=250 
     URL to redirect after payment method is added. 
     
     
     
     
     
    customer[id]
     
    required, string, max chars=50 
     Identifier of the customer. 
     
     
    card[gateway_account_id]
     
    optional, string, max chars=50 
     The gateway account in which this payment source is stored. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Collect Now
      
     
    Idempotency Supported
     
     
    This API generates a hosted page URL to collect due payments for the customer.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/collect_now \
     -u {site_api_key}:\
     -d "customer[id]"="__test__KyVnGlSBWmHH82Pw" \
     -d "card[gateway_account_id]"="gw___test__KyVnGlSBWmAIk2Ph" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/collect_now \
     -u {site_api_key}:\
     -d "customer[id]"="__test__KyVnGlSBWmHH82Pw" \
     -d "card[gateway_account_id]"="gw___test__KyVnGlSBWmAIk2Ph" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517506010,
        "embed": true,
        "expires_at": 1517592410,
        "id": "__test__4cq9mwW1cuoD085nSBLh0KUMKdphVO5cC",
        "object": "hosted_page",
        "resource_version": 1517506010000,
        "state": "created",
        "type": "collect_now",
        "updated_at": 1517506010,
        "url": "https://yourapp.chargebee.com/pages/v3/__test__4cq9mwW1cuoD085nSBLh0KUMKdphVO5cC/collect_now"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/collect_now
    
     
    Method
     
     
    Input Parameters
     
      
     
    redirect_url[]
     
    
      optional, string, max chars=250 
     Used to specify the destination URL to which a user is redirected after invoices are paid. The transaction ID of the transactions made through the Pay Now hosted page will be sent as return variables along with the URL. 
     
    currency_code[]
     
    
      optional, string, max chars=3 
     The currency code (ISO 4217 format) of the specified credit amount. 
     
     
     
     
     
    customer[id]
     
    required, string, max chars=50 
     Identifier of the customer. 
     
     
    card[gateway_account_id]
     
    optional, string, max chars=50 
     The gateway account in which this payment source is stored. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Accept a quote
      
     
    Idempotency Supported
     
     
    This API generates a hosted page URL for the customer to accept a quote. If the hosted page URL has expired, a new URL will be generated automatically.
      
    Notes
     
       
    • Hosted page URL to accept a quote cannot be generated for one-time charges. 
      •  
    • Customers with existing subscriptions can generate a quote for new subscriptions. However, Hosted page URL to accept a quote cannot be generated for new subscriptions in V1 and V2 hosted pages. 
      •  
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote \
     -u {site_api_key}:\
     -d "quote[id]"="1" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote \
     -u {site_api_key}:\
     -d "quote[id]"="1" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517505980,
        "embed": true,
        "expires_at": 1517596199,
        "id": "__test__IKNpcdSoRFV0hFeci8SSkUbhZYjle2dKh",
        "object": "hosted_page",
        "resource_version": 1517505981000,
        "state": "created",
        "type": "checkout_existing",
        "updated_at": 1517505981,
        "url": "https://yourapp.chargebee.com/pages/v2/__test__IKNpcdSoRFV0hFeci8SSkUbhZYjle2dKh/checkout"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote
    
     
    Method
     
     
    Input Parameters
     
      
     
    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=<hosted_page_id>&state=succeeded
      •  
    • This parameter is not applicable for iframe messaging.
      •  
     
     
    layout[]
     
    
      optional, enumerated string 
     Specifies the checkout layout that overrides the default checkout layout configured in the Checkout & Self-Serve Portal settings. . 
    Possible values are
     
    in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
     
    in_appIndicates in-app checkout versionfull_pageIndicates full page checkout version
     
     Show all values[+]
     
     
     
     
     
    quote[id]
     
    required, string, max chars=50 
     The quote number. Acts as a identifier for quote and typically generated sequentially. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Extend Subscription
      
     
    Idempotency Supported
     
     
    This API generates a hosted page URL to extend the billing cycle of a subscription.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \
     -u {site_api_key}:\
     -d billing_cycle=2 \
     -d expiry=14 \
     -d "subscription[id]"="__test__KyVnHhSBWmIgw2u6" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \
     -u {site_api_key}:\
     -d billing_cycle=2 \
     -d expiry=14 \
     -d "subscription[id]"="__test__KyVnHhSBWmIgw2u6" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517506012,
        "embed": true,
        "expires_at": 1518715612,
        "id": "__test__Bct8ySC6A1eV2GdMcdUl7dzovgyKhAz4M",
        "object": "hosted_page",
        "resource_version": 1517506012000,
        "state": "created",
        "type": "extend_subscription",
        "updated_at": 1517506012,
        "url": "https://yourapp.chargebee.com/pages/v3/__test__Bct8ySC6A1eV2GdMcdUl7dzovgyKhAz4M/"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription
    
     
    Method
     
     
    Input Parameters
     
      
     
    expiry[]
     
    
      optional, integer, min=1, max=500 
     Expiry (in days) for the link generated. No expiry will be set if this is not specified. 
     
    billing_cycle[]
     
    
      optional, integer, min=1 
     Number of billing cycles to extend. If not specified, plan's billing cycle will be used. 
     
     
     
     
     
    subscription[id]
     
    required, string, max chars=50 
     A unique and immutable identifier for the subscription. If not provided, it is autogenerated. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Checkout Gift subscription for Items
      
     
    Idempotency Supported
     
     
     Creates a hosted page for a customer (called the gifter) to gift a subscription to another customer (called the receiver). 
     

    Gifter customer resource lookup and creation
     

     When gifter[customer_id] is provided, it is looked up in Chargebee when the gifter completes the hosted page checkout. If not found, a new customer resource is created with this ID. 
     

    Multiple business entities
     

     If multiple business entities are created for the site, the lookup and creation of the gifter customer resource happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site. 
     

    Gift receiver customer resource lookup and creation
     

     Once the gifter checks out using the hosted page returned by this endpoint, Chargebee checks if a customer resource with the receiver’s email address exists. The first such customer record is considered the receiver’s customer resource. A new customer resource is created for the receiver if none are found. 
     

    Multiple business entities
     

     If multiple business entities are created for the site, the lookup and creation of the gift receiver’s customer resource happen within the context of the business entity of the gifter 
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items \
     -u {site_api_key}:\
     -d "gifter[customer_id]"="gifter" \
     -d "subscription_items[item_price_id][0]"="gift-plan-USD" \
     -d "subscription_items[quantity][0]"=2 
     
    
      copy
      
    Click to Copy
     
    Checkout gift subscription for items
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items \
     -u {site_api_key}:\
     -d "gifter[customer_id]"="gifter" \
     -d "subscription_items[item_price_id][0]"="gift-plan-USD" \
     -d "subscription_items[quantity][0]"=2 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517484798,
        "embed": false,
        "expires_at": 1517488398,
        "id": "__gift___test__gPY4LqKkoEdrcdWdxpl6nABSZu2oDcCpR",
        "object": "hosted_page",
        "resource_version": 1517484798645,
        "state": "created",
        "type": "checkout_gift",
        "updated_at": 1517484798,
        "url": "https://yourapp.chargebee.com/pages/v3/__gift___test__gPY4LqKkoEdrcdWdxpl6nABSZu2oDcCpR/"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items
    
     
    Method
     
     
    Input Parameters
     
      
     
    business_entity_id[]
     
    
      optional, string, max chars=50 
     
     Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site. 
    

     Note

    An alternative way of passing this parameter is by means of a custom HTTP header.
     
    

     See also

    Gifter customer resource lookup and creation.
     
          
     
    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=<hosted_page_id>&state=succeeded
      •  
    • This parameter is not applicable for iframe messaging.
      •  
     
     
    coupon_ids[[0..n]][0..n]
     
    
      optional, list of string 
     List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes. 
     
     
     
     
     
    gifter[customer_id]
     
    optional, string, max chars=50 
     
    
The customer ID of the gifter. If not provided, the gifter customer resource is created with an autogenerated ID on checkout.

    

    
    See also


    Gifter customer resource lookup and creation
    

     
    gifter[locale]
     
    optional, string, max chars=50 
     Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication. 
     
     
    subscription_items[item_price_id][0..n]
     
    optional, string, max chars=100 
     The unique identifier of the item price. 
    subscription_items[quantity][0..n]
     
    optional, integer, default=1, min=1 
     The quantity of the item purchased 
    subscription_items[quantity_in_decimal][0..n]
     
    optional, string, max chars=33 
     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. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Claim a Gift subscription
      
     
    Idempotency Supported
     
     
    This API generates a hosted page URL to claim a gifted subscription.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift \
     -u {site_api_key}:\
     -d "gift[id]"="__test__KyVnHhSBWmGdM2tv__test__21cdZvclBhOULyCT1SBUPDKjoXsuc3wdj" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift \
     -u {site_api_key}:\
     -d "gift[id]"="__test__KyVnHhSBWmGdM2tv__test__21cdZvclBhOULyCT1SBUPDKjoXsuc3wdj" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517678804,
        "embed": false,
        "expires_at": 1517682404,
        "id": "__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd",
        "object": "hosted_page",
        "resource_version": 1517678804000,
        "state": "created",
        "type": "claim_gift",
        "updated_at": 1517678804,
        "url": "https://yourapp.chargebee.com/pages/v3/__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd/claim_gift"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift
    
     
    Method
     
     
    Input Parameters
     
      
     
    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=<hosted_page_id>&state=succeeded
      •  
    • This parameter is not applicable for iframe messaging.
      •  
     
     
     
     
     
     
    gift[id]
     
    required, string, max chars=150 
     Uniquely identifies a gift 
     
     
    customer[locale]
     
    optional, string, max chars=50 
     Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Retrieve Direct Debit Agreement PDF
      
     
    Idempotency Supported
     
     
    This is applicable only for Direct Debit via SEPA, Bacs, Bg Autogiro, BECS (for both Australia and New Zealand) and PAD. For Direct Debit, the customer needs to accept an agreement that allows the merchant to debit their bank account. This agreement PDF allows you to easily display scheme-rules compliant Direct Debit mandates to your customers.
     

    This API retrieves the redirect link to the corresponding agreement for customers. The agreement PDF can be your “Thank You” page or sent by email to customers. Communicating this PDF to your customers is mandatory.
     

    Customer locale is used to generate the PDF in the required language. If a customer language is not supported, the PDF is generated in English. Checkout the list of languages supported by GoCardless.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWmKRg2uT"
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__KyVnHhSBWmKRg2uT"
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517506018,
        "embed": false,
        "expires_at": 1520098018,
        "id": "__test__AUCK2LNxny5cXiA1JcdBQE9283e5McdvCC",
        "object": "hosted_page",
        "resource_version": 1517506018000,
        "state": "created",
        "type": "agreement_pfd",
        "updated_at": 1517506018,
        "url": "https://yourapp.chargebee.com/action_pages/__test__AUCK2LNxny5cXiA1JcdBQE9283e5McdvCC/agreement_pdf"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf
    
     
    Method
     
     
    Input Parameters
     
      
     
    payment_source_id[]
     
    
      required, string, max chars=40 
     Payment source to be used for this payment. 
     
     
        
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Acknowledge a hosted page
      
     
    Idempotency Supported
     
     
    When a hosted page is successfully completed by the user and processed by Chargebee, its state is automatically changed to succeeded. Acknowledging a hosted page confirms that you have moved the customer details from Chargebee into your system and are ready to fulfill it. This API is used to acknowledge the hosted page in succeeded state and change its state to acknowledged.

    Note: The hosted page status must be succeeded for this API call to be allowed.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__p541yXSwQO7jD2oRNFlBSvqU2s0oiWY0/acknowledge \
     -X POST  \
     -u {site_api_key}:
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__p541yXSwQO7jD2oRNFlBSvqU2s0oiWY0/acknowledge \
     -X POST  \
     -u {site_api_key}:
     
     
    
    Sample Response [ JSON ]
      
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/{hosted-page-id}/acknowledge
    
     
    Method
     
      
       
     
        
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Retrieve a hosted page
      
      
     
     When you retrieve a hosted page whose status is successful, the content attribute has the following objects based on the type of the hosted page. 
     

     

     
  
  
     
   type of hosted page 
   content attribute constituents 
  
     
  
     
   checkout_new 
    
    
       
     
    • customer: the object representing the details of the Customer for whom the subscription was created. 
      •  
     
    • subscription: the new Subscription object created.
      •  
     
    • card: the Card object if the payment method type used was card. 
      •  
     
    • invoice: the Invoice object, if an invoice was generated.
      •  
    
         		 
  
     
  
     
   checkout_existing 
    
    
       
     
    • customer: the object representing the details of the Customer whose subscription was changed. 
      •  
     
    • subscription: the updated Subscription object created.
      •  
     
    • card: the Card object if the payment method type used was card. 
      •  
     
    • invoice: the Invoice object, if an invoice was generated for the subscription change. 
      •  
    
         		 
  
     
  
     
   update_payment_method 
    
    
       
     
    • customer: the object representing the details of the Customer whose subscription was changed. 
      •  
     
    • card: the Card object if the new payment method added was of type card. 
      •  
    
         		 
  
     
 
     
   pre_cancel 
    
 
      retention: Use the bypass flag in this object to route the cancellation flow to the merchants’ portal or the Chargebee Retention.
 
    • If bypass flag is true, you should route the end-customers to your native cancellation flow. 
      •  
    •  If the bypass flag is false, you should route the end-customers to the hosted page URL. 
      •  
 Note: Retention is currently in beta. To enable Retention, Contact Support.  
 
 
 
         		 
  
     
 
     collect_now 
    • transactions: this object should contain a list of 
      transactions triggered from the collect_now
      hosted page. Each transaction in the list should be represented as an array that includes relevant information about the transaction, such as transaction ID, customer ID, amount, currency, payment method, and any other relevant details.
    • customer: this object should contain the customer record associated with the transaction. The key, customer_id is used to link the transaction to the corresponding customer record.
    		 
          

      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \
     -u {site_api_key}:
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \
     -u {site_api_key}:
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "created_at": 1517506016,
        "embed": true,
        "expires_at": 1517509616,
        "id": "__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r",
        "object": "hosted_page",
        "resource_version": 1517506016000,
        "state": "created",
        "type": "checkout_existing",
        "updated_at": 1517506016,
        "url": "https://yourapp.chargebee.com/pages/v2/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r/checkout"
    }
}
     
    
      URL Format
      GET
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/{hosted-page-id}
    
     
    Method
     
      
       
     
        
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      List hosted pages
      
      
     
     This API retrieves the list of hosted page resources. 
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "list": [
        {
            "hosted_page": {
                "created_at": 1517678804,
                "embed": false,
                "expires_at": 1517682404,
                "id": "__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd",
                "object": "hosted_page",
                "resource_version": 1517678804000,
                "state": "created",
                "type": "claim_gift",
                "updated_at": 1517678804,
                "url": "https://yourapp.chargebee.com/pages/v3/__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd/claim_gift"
            }
        },
        {..}
    ],
    "next_offset": "[\"1517506012000\",\"186000000018\"]"
}
     
    
      URL Format
      GET
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages
    
     
    Method
     
     
    Input Parameters
     
    limit[]
     
    
      optional, integer, default=10, min=1, max=100 
     The number of resources to be returned. 
    offset[]
     
    
      optional, string, max chars=1000 
     Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call. 
       
     
       
    Filter Params 
     
    
          For operator usages, see the
          Pagination and Filtering
          section.
        
     
    id[<operator>]
      
     optional, string filter
     Unique identifier generated for each hosted page requested. Possible values are :  
    Supported operators : is, is_not, starts_with, in, not_in
    

    Example → id[is] = "Edi69nxpu6BeGBd9Fjcd0tqCSwb0sRcuKa"
     
     
     
    id[is][operator]
     
     optional, string, min chars=1 filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    id[is_not][operator]
     
     optional, string, min chars=1 filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    id[starts_with][operator]
     
     optional, string, min chars=1 filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    id[in][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    id[not_in][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
    type[<operator>]
      
     optional, enumerated string filter
     Type of the requested hosted page.  Possible values are : checkout_new, checkout_existing, update_payment_method, manage_payment_sources, collect_now, extend_subscription, checkout_one_time, pre_cancel, view_voucher 
    Supported operators : is, is_not, in, not_in
    

    Example → type[is] = "checkout_new"
     
     
     
    type[is][operator]
     
     optional, enumerated string filter
      Possible values are : checkout_new, checkout_existing, update_payment_method, manage_payment_sources, collect_now, extend_subscription, checkout_one_time, pre_cancel, view_voucher 
    Supported operators : 
    

    Example → 
     
    type[is_not][operator]
     
     optional, enumerated string filter
      Possible values are : checkout_new, checkout_existing, update_payment_method, manage_payment_sources, collect_now, extend_subscription, checkout_one_time, pre_cancel, view_voucher 
    Supported operators : 
    

    Example → 
     
    type[in][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    type[not_in][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
    state[<operator>]
      
     optional, enumerated string filter
     Indicating the current state of the hosted page resource.  Possible values are : created, requested, succeeded, cancelled, acknowledged 
    Supported operators : is, is_not, in, not_in
    

    Example → state[is] = "succeeded"
     
     
     
    state[is][operator]
     
     optional, enumerated string filter
      Possible values are : created, requested, succeeded, cancelled, acknowledged 
    Supported operators : 
    

    Example → 
     
    state[is_not][operator]
     
     optional, enumerated string filter
      Possible values are : created, requested, succeeded, cancelled, acknowledged 
    Supported operators : 
    

    Example → 
     
    state[in][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    state[not_in][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
    updated_at[<operator>]
      
     optional, timestamp(UTC) in seconds filter
     Timestamp indicating when this hosted page was last updated. Possible values are :  
    Supported operators : after, before, on, between
    

    Example → updated_at[after] = "1490784813"
     
     
     
    updated_at[after][operator]
     
     optional, timestamp(UTC) in seconds filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    updated_at[before][operator]
     
     optional, timestamp(UTC) in seconds filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    updated_at[on][operator]
     
     optional, timestamp(UTC) in seconds filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    updated_at[between][operator]
     
     optional, string filter
      Possible values are :  
    Supported operators : 
    

    Example → 
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
    next_offset  next_offset
     
     optional, string, max chars=1000
     This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Create a pre-cancel hosted page
      
     
    Idempotency Supported
     
     
    Creates a hosted_page resource of type pre_cancel. Route canceling users to this page to provide them a retention experience and start saving revenue.
    The hosted page is created in accordance with the retention experience configured in the Chargebee Retention app, along with the data provided as input to this endpoint. Call the endpoint before your customer clicks the Cancel button, and when they do, route them to the url in the endpoint response.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/pre_cancel \
     -u {site_api_key}:\
     -d pass_thru_content='{custom :  {discount_percent: 10}}' \
     -d "subscription[id]"="__test__KyVnHhSBWmCoF2tJ" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/pre_cancel \
     -u {site_api_key}:\
     -d pass_thru_content='{custom :  {discount_percent: 10}}' \
     -d "subscription[id]"="__test__KyVnHhSBWmCoF2tJ" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "id": "__dev__uxMMdSCbO8zweGryJDU37zfbdGxC3Gn9",
        "type": "pre_cancel",
        "url": "https://app.brightback.com/session/mVS0ecj6tswr3Ss",
        "state": "created",
        "pass_thru_content": "{custom :  {discount_percentage: 10}}",
        "embed": false,
        "created_at": 1653382696,
        "expires_at": 1653386296,
        "object": "hosted_page"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/pre_cancel
    
     
    Method
     
     
    Input Parameters
     
      
     
    pass_thru_content[]
     
    
      optional, string, max chars=2048 
     
    Additional data to be passed to Chargebee Retention. Only the value of pass_thru_content.custom is sent to Chargebee Retention. It is sent as the value of the custom property. The fields provided in pass_thru_content.custom must be preconfigured in Chargebee Retention.
    

    Although only pass_thru_content.custom is sent to Chargebee Retention, all of pass_thru_content is stored by Chargebee billing and is retrievable as an attribute of the hosted_page.
    .     
     
    cancel_url[]
     
    
      optional, string, max chars=250 
     The customer is sent to this URL if they finally decide to cancel the subscription, despite the attempt to retain them. 
     
    redirect_url[]
     
    
      optional, string, max chars=250 
     The customer is sent to this URL upon successful retention. In other words, this is the page to which the customer is sent when they decide not to cancel the subscription. 
     
     
     
     
     
    subscription[id]
     
    required, string, max chars=50 
     The unique ID of the subscription which the customer wants to cancel. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Notify an event
      
     
    Idempotency Supported
     
     
    Use this API to notify Chargebee about important events that occur on your web pages, such as subscription cancellations. An event contains data about affected resources and additional details such as when the change occurred.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/events \
     -u {site_api_key}:\
     -d event_name="CANCELLATION_PAGE_LOADED" \
     -d occurred_at=1435054328 \
     -d event_data='{"subscription_id" : "__test__KyVnHhSBWmCoF2tJ"}'
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/events \
     -u {site_api_key}:\
     -d event_name="CANCELLATION_PAGE_LOADED" \
     -d occurred_at=1435054328 \
     -d event_data='{"subscription_id" : "__test__KyVnHhSBWmCoF2tJ"}'
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "success": true
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/events
    
     
    Method
     
     
    Input Parameters
     
      
     
    event_name[]
     
    
      required, enumerated string 
     The event that need to passed to a different system. 
    Possible values are
     
    cancellation_page_loadedIndicates native cancellation flow provided by the merchant is loaded rather than the retention flow.
     
    cancellation_page_loadedIndicates native cancellation flow provided by the merchant is loaded rather than the retention flow.
     
     Show all values[+]
     
    occurred_at[]
     
    
      optional, timestamp(UTC) in seconds 
     Timestamp indicating when this event had occurred.
. 
     
    event_data[]
     
    
      required, jsonobject 
     
    The meta data description of the event in key-value pair. The value is a JSON object with the following keys and their values.
    

    • subscription_id: A unique and immutable identifier for the subscription.
    .     
     
     
        
     
    Returns
     
    success  success
     
     required, boolean
     
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x
    
    
      Create a hosted page to view Boleto vouchers
      
     
    Idempotency Supported
     
     
    Creates a hosted_page resource of type, view_voucher. When your end customers choose the Boleto payment method, you can generate a voucher for their pending invoice. Using this API, you can create a voucher_detail hosted page for your customers and email them a link to this hosted page. Your customers can review the voucher details on the page by clicking the link in the email.
      
    Notes
     
     
    
      Sample Request
    
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/view_voucher \
     -u {site_api_key}:\
     -d "customer[locale]"="fr-CA" 
     
    
      copy
      
    Click to Copy
     
     
    curl  https://{site}.chargebee.com/api/v2/hosted_pages/view_voucher \
     -u {site_api_key}:\
     -d "customer[locale]"="fr-CA" 
     
     
    
    Sample Response [ JSON ]
     
    Show more...
     
    {
    "hosted_page": {
        "id": "__dev__6FL1CcdDKgO1Eui9ys7pkFDirQcu5twVhX",
        "type": "voucher_detail",
        "url": "https://yourapp.chargebee.com/pages/v3/__test__4cq9mwW1cuoD085nSBLh0KUMKdphVO5cC/view_voucher",
        "state": "created",
        "embed": false,
        "created_at": 1653044153,
        "expires_at": 1653047753,
        "object": "hosted_page"
    }
}
     
    
      URL Format
      POST
     
    
      https://{site}.chargebee.com/api/v2/hosted_pages/view_voucher
    
     
    Method
     
     
    Input Parameters
     
       
     
     
     
     
    payment_voucher[id]
     
    required, string, max chars=40 
     The unique ID of the voucher which the customer wants to view. 
     
     
    customer[locale]
     
    optional, string, max chars=50 
     Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication. 
       
     
    Returns
     
    hosted_page  hosted_page
     
    
      always returned 
     Resource object representing hosted_page
     
    Sample admin console URL
     
    
      https://{site}.chargebee.com/admin-console/hosted_pages/123x