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/"
}

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 Subscription.checkout_existingCheckout existing Subscription.update_payment_methodUpdate Payment Method for a Customer.

manage_payment_sourcesManage Payments for a customer.collect_nowCollect Unpaid Invoices for a Customer.extend_subscriptionTo extend a Subscription period.checkout_one_timeCheckout one time.pre_cancelThis hosted page is used to help retain customers when they attempt to cancel their account or subscription.

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

pass_thru_content

optional, string, max chars=2048
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.

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.

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:

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.
Send the customer to the Checkout url received in the response.
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.
Retrieve the hosted page at this stage to get the invoice details.

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 the ID provided, 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.

Sample Request

# 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 item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 \
     -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"

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 item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 \
     -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"

Sample Response [ JSON ]

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

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

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]

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
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.

customer

Parameters for customer
pass parameters as customer[<param name>]

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

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[phone]

optional, string, max chars=50
Phone number of the customer

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

Parameters for invoice
pass parameters as invoice[<param name>]

invoice[po_number]

optional, string, max chars=100
Purchase Order Number for this invoice.

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50
The gateway account in which this payment source is stored.

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

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.

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

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]

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]

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

item_prices

Parameters for item_prices. Multiple item_prices can be passed by specifying unique indices.
pass parameters as item_prices[<param name>][<idx:0..n>]

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

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

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.

charges

Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]

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:

India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
The AvaTax for Sales integration has been enabled in Chargebee.

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

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

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.

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. This is only applicable when discount.type is fixed_amount.

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.

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

Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]

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]

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:

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.

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:

hosted_page

always returned
Resource object representing hosted_page

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:

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.
Send the customer to the Checkout url received in the response.
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.
Retrieve the hosted page at this stage to get the subscription and invoice details.

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 the ID provided 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.

Sample Request

# 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

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 ]

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

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

business_entity_id

optional, string, max chars=50

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]

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.

coupon_ids[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
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.

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

Parameters for subscription
pass parameters as subscription[<param name>]

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.

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.

subscription[affiliate_token]

optional, string, max chars=250
A unique tracking token

customer

Parameters for customer
pass parameters as customer[<param name>]

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[taxability]

optional, enumerated string, default=taxable
Specifies if the customer is liable for tax

Possible values are

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.

customer[locale]

customer[phone]

optional, string, max chars=50
Phone number of the customer

customer[vat_number]

customer[vat_number_prefix]

customer[is_einvoice_enabled]

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]

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]

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

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50
The gateway account in which this payment source is stored.

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

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]

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]

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

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

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]

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]

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

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string, default=cancel
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.

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

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

required, string, max chars=100
The unique identifier of the item price.

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]

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
The service period of the item in days from the day of charge.

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

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

required, enumerated string
The amount on the invoice to which the discount is applied.

Possible values are

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.

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.

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. This is only applicable when discount.type is fixed_amount.

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.

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

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

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]

item_tiers[ending_unit_in_decimal][0..n]

item_tiers[price_in_decimal][0..n]

entity_identifiers

Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]

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]

Tip:

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:

entity_identifiers[operation][0..n]

optional, enumerated string
The operation to be performed for the entity_identifier.

Possible values are

entity_identifiers[standard][0..n]

Tip:

hosted_page

always returned
Resource object representing hosted_page

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

The following steps describe how best to use this API:

Provide item prices, coupons and a host of other details such as billing and shipping addresses to be prefilled for the customer on the checkout page.
Send the customer to the Checkout url received in the response. They can now add a payment method or use an existing one, to complete the checkout.
The subscription is updated and the customer is redirected to the redirect_url with the id and state attributes passed as query string parameters.
Although the customer will be redirected to the redirect_url after successful checkout, we do not recommend relying on it for completing critical post-checkout actions. This is because redirection may not happen due to unforeseen reasons. Chargebee recommends listening to appropriate webhooks such as subscription_created or invoice_generated to verify a successful checkout.
Retrieve the hosted page at this stage to get the subscription and invoice details.

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

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 ]

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

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

mandatory_items_to_remove[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
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

coupon_ids[0..n]

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

reactivate

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

force_term_reset

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

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
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.

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

Parameters for subscription
pass parameters as subscription[<param name>]

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

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 CreditboletoBoleto

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]

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[vat_number]

customer[vat_number_prefix]

customer[is_einvoice_enabled]

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]

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

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50
The gateway account in which this payment source is stored.

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string, default=cancel
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.

contract_term[cancellation_cutoff_period]

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

subscription_items[item_price_id][0..n]

required, string, max chars=100
The unique identifier of the item price.

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]

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]

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
The service period of the item in days from the day of charge.

subscription_items[charge_on_event][0..n]

Possible values are

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.

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[apply_on][0..n]

required, enumerated string
The amount on the invoice to which the discount is applied.

Possible values are

discounts[duration_type][0..n]

required, enumerated string
Specifies the time duration for which this discount is attached to the subscription.

Possible values are

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.

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. This is only applicable when discount.type is fixed_amount.

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.

discounts[included_in_mrr][0..n]

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.

discounts[id][0..n]

optional, string, max chars=50
An immutable unique id for the discount. It is always auto-generated.

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

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, min=0
The overridden price of the tier. The value depends on the type of currency.

item_tiers[starting_unit_in_decimal][0..n]

item_tiers[ending_unit_in_decimal][0..n]

item_tiers[price_in_decimal][0..n]

entity_identifiers

Parameters for entity_identifiers. Multiple entity_identifiers can be passed by specifying unique indices.
pass parameters as entity_identifiers[<param name>][<idx:0..n>]

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]

Tip:

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:

entity_identifiers[operation][0..n]

optional, enumerated string
The operation to be performed for the entity_identifier.

Possible values are

entity_identifiers[standard][0..n]

Tip:

hosted_page

always returned
Resource object representing hosted_page

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.

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

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 ]

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

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
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.

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

Parameters for customer
pass parameters as customer[<param name>]

customer[id]

required, string, max chars=50
Identifier of the customer.

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50
The gateway account in which this payment source is stored.

hosted_page

always returned
Resource object representing hosted_page

This API generates a hosted page URL to add new or update existing payment sources for the customer.

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

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 ]

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

redirect_url

optional, string, max chars=250
URL to redirect after payment method is added.

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[id]

required, string, max chars=50
Identifier of the customer.

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50
The gateway account in which this payment source is stored.

hosted_page

always returned
Resource object representing hosted_page

This API generates a hosted page URL to collect due payments for the customer.

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

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 ]

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

redirect_url

optional, string, max chars=250
URL to redirect after invoices are paid.

currency_code

optional, string, max chars=3
The currency code (ISO 4217 format) of the specified credit amount.

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[id]

required, string, max chars=50
Identifier of the customer.

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50
The gateway account in which this payment source is stored.

hosted_page

always returned
Resource object representing hosted_page

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 \
     -X POST  \
     -u {site_api_key}:\
     -d quote[id]="1"

copy

curl  https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote \
     -X POST  \
     -u {site_api_key}:\
     -d quote[id]="1"

Sample Response [ JSON ]

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

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.

quote

Parameters for quote
pass parameters as quote[<param name>]

quote[id]

required, string, max chars=50
The quote number. Acts as a identifier for quote and typically generated sequentially.

hosted_page

always returned
Resource object representing hosted_page

This API generates a hosted page URL to extend the billing cycle of a subscription.

Sample Request

curl  https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmIgw2u6" \
     -d billing_cycle=2 \
     -d expiry=14

copy

curl  https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmIgw2u6" \
     -d billing_cycle=2 \
     -d expiry=14

Sample Response [ JSON ]

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

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

Parameters for subscription
pass parameters as subscription[<param name>]

subscription[id]

required, string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

hosted_page

always returned
Resource object representing hosted_page

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

Sample Request

# Checkout Gift subscription for Items
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items \
     -X POST  \
     -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

# Checkout Gift subscription for Items
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items \
     -X POST  \
     -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 ]

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

business_entity_id

optional, string, max chars=50

Note

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

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]

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

gifter

Parameters for gifter
pass parameters as gifter[<param name>]

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.

gifter[locale]

subscription_items

Parameters for subscription_items. Multiple subscription_items can be passed by specifying unique indices.
pass parameters as subscription_items[<param name>][<idx:0..n>]

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.

hosted_page

always returned
Resource object representing hosted_page

This API generates a hosted page URL to claim a gifted subscription.

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

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 ]

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

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

Parameters for gift
pass parameters as gift[<param name>]

gift[id]

required, string, max chars=150
Uniquely identifies a gift

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[locale]

hosted_page

always returned
Resource object representing hosted_page

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.

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

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 ]

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

payment_source_id

required, string, max chars=40
Payment source to be used for this payment.

hosted_page

always returned
Resource object representing hosted_page

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.

URL Format POST

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

hosted_page

always returned
Resource object representing 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.

Sample Request

curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/hosted_pages/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r \
     -u {site_api_key}:

Sample Response [ JSON ]

{"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}

hosted_page

always returned
Resource object representing hosted_page

This API retrieves the list of hosted page resources.

Sample Request

curl  https://{site}.chargebee.com/api/v2/hosted_pages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

curl  https://{site}.chargebee.com/api/v2/hosted_pages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

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

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.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "Edi69nxpu6BeGBd9Fjcd0tqCSwb0sRcuKa"

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.
Supported operators : is, is_not, in, not_in

Example → type[is] = "checkout_new"

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_not] = "succeeded"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
Timestamp indicating when this hosted page was last updated.
Supported operators : after, before, on, between

Example → updated_at[after] = "1490784813"

hosted_page

always returned
Resource object representing hosted_page

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

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.

Sample Request

curl  https://{site}.chargebee.com/api/v2/hosted_pages/pre_cancel \
     -X POST  \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmCoF2tJ" \
     -d pass_thru_content="{custom :  {discount_percent: 10}}"

copy

curl  https://{site}.chargebee.com/api/v2/hosted_pages/pre_cancel \
     -X POST  \
     -u {site_api_key}:\
     -d subscription[id]="__test__KyVnHhSBWmCoF2tJ" \
     -d pass_thru_content="{custom :  {discount_percent: 10}}"

Sample Response [ JSON ]

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

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

Parameters for subscription
pass parameters as subscription[<param name>]

subscription[id]

required, string, max chars=50
The unique ID of the subscription which the customer wants to cancel.

hosted_page

always returned
Resource object representing hosted_page

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.

Sample Request

curl  https://{site}.chargebee.com/api/v2/hosted_pages/events \
     -X POST  \
     -u {site_api_key}:\
     -d type="cancellation_page_loaded" \
     -d occurred_at=1435054328 \
     -d event_data="{subscription_id : '__test__KyVnHhSBWmCoF2tJ'}"

copy

curl  https://{site}.chargebee.com/api/v2/hosted_pages/events \
     -X POST  \
     -u {site_api_key}:\
     -d type="cancellation_page_loaded" \
     -d occurred_at=1435054328 \
     -d event_data="{subscription_id : '__test__KyVnHhSBWmCoF2tJ'}"

Sample Response [ JSON ]

{"success": true}

URL Format POST

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

type

required, enumerated string
The type of event being sent to Chargebee from the events API.

Possible values are

cancellation_page_loadedThis event should be sent when Chargebee Retention’s A/B testing is enabled, and the end-user is directed to your cancellation flow instead of Chargebee’s Retention flow.

This event should be used as a metric to measure how effective Chargebee Retention is when compared to your cancellation flow.
When the Pre cancel API returns the value for the bypass flag as true , the end-user should be sent to your cancellation flow and not the Chargebee’s retention flow.
Retention is currently in beta. To enable Retention, Contact Support.

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.

success

optional, boolean
Event was processed successfully

Sample hosted page [ JSON ]

Hosted page attributes

Checkout charge-items and one-time charges¶

Customer resource lookup and creation

Multiple business entities

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Create checkout for a new subscription¶

Customer resource lookup and creation

Multiple business entities

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Create checkout to update a subscription¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Update payment method¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Manage Payment Sources¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Collect Now¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Accept a quote¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Extend Subscription¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Checkout Gift subscription for Items¶

Gifter customer resource lookup and creation

Multiple business entities

Gift receiver customer resource lookup and creation

Multiple business entities

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Claim a Gift subscription¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Retrieve Direct Debit Agreement PDF¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Acknowledge a hosted page¶

URL Format POST

Returns

Retrieve a hosted page¶

Sample Response [ JSON ]

URL Format GET

Returns

List hosted pages¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.