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
Unique identifier generated for each hosted page requested.
optional, string, max chars=70
type
Type of the requested hosted page.
optional, enumerated string
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.
Show all values[+]
url
Unique URL for the hosted page that will be included in your website.
optional, string, max chars=250
state
Indicating the current state of the hosted page resource.
optional, enumerated string, default=created
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
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.
optional, string, max chars=2048
created_at
Indicates when this hosted page url is generated.
optional, timestamp(UTC) in seconds
expires_at
Indicates when this hosted page url will expire. After this, the hosted page cannot be accessed.
optional, timestamp(UTC) in seconds
content
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.
jsonobject
updated_at
Timestamp indicating when this hosted page was last updated.
optional, timestamp(UTC) in seconds
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number.
optional, long
checkout_info
Customer Info (email, first name and last name) given in the checkout page used for tracking abandoned carts.
Learn more.
optional, jsonobject

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

The following steps describe how best to use this API:

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

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

URL Format POST

https://{site}.chargebee.com/api/v2/hosted_pages/checkout_one_time_for_items
invoice_note
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
optional, string, max chars=2000
coupon_ids[0..n]
List of Coupons to be added.
optional, list of string
currency_code
The currency code (ISO 4217 format) of the invoice amount.
required if Multicurrency is enabled, string, max chars=3
redirect_url
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 :
  • 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.
    optional, string, max chars=250
cancel_url
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.
    optional, string, max chars=250
pass_thru_content
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.
optional, string, max chars=2048
+
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[id]
Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50
customer[email]
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
customer[first_name]
First name of the customer. If not provided it will be got from contact information entered in the hosted page .
optional, string, max chars=150
customer[last_name]
Last name of the customer. If not provided it will be got from contact information entered in the hosted page .
optional, string, max chars=150
customer[company]
Company name of the customer.
optional, string, max chars=250
customer[taxability]
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable
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]
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.
optional, string, max chars=50
customer[phone]
Phone number of the customer.
optional, string, max chars=50
customer[vat_number]
VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20
customer[vat_number_prefix]
VAT/ Tax registration number prefix of the customer. Learn more.
optional, string, max chars=10
customer[consolidated_invoicing]
Applicable when consolidated invoicing is enabled. Indicates whether invoice consolidation should happen during subscription renewals. Needs to be set only if this value is different from the defaults configured.
optional, boolean
+
invoice
Parameters for invoice
pass parameters as invoice[<param name>]
invoice[po_number]
Purchase Order Number for this invoice.
optional, string, max chars=100
+
card
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
billing_address[email]
The email address.
optional, string, max chars=70
billing_address[company]
The company name.
optional, string, max chars=250
billing_address[phone]
The phone number.
optional, string, max chars=50
billing_address[line1]
Address line 1.
optional, string, max chars=150
billing_address[line2]
Address line 2.
optional, string, max chars=150
billing_address[line3]
Address line 3.
optional, string, max chars=150
billing_address[city]
The name of the city.
optional, string, max chars=50
billing_address[state_code]
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).
optional, string, max chars=50
billing_address[state]
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50
billing_address[zip]
Zip or Postal code.
optional, string, max chars=20
billing_address[country]
2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
shipping_address[email]
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
shipping_address[phone]
The phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
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).
optional, string, max chars=50
shipping_address[state]
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
+
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]
A unique ID for your system to identify the item price.
optional, string, max chars=100
item_prices[quantity][0..n]
Item price quantity.
optional, integer, min=1
item_prices[quantity_in_decimal][0..n]
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.
optional, string, max chars=33
item_prices[unit_price][0..n]
Amount that will override the item's default price. The unit depends on the type of currency.
optional, in cents, min=0
item_prices[unit_price_in_decimal][0..n]
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.
optional, string, max chars=33
item_prices[date_from][0..n]
The time when the service period for the item starts.
optional, timestamp(UTC) in seconds
item_prices[date_to][0..n]
The time when the service period for the item ends.
optional, timestamp(UTC) in seconds
+
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]
The id of the item price to which this tier belongs.
optional, string, max chars=100
item_tiers[starting_unit][0..n]
The lowest value in the quantity tier.
optional, integer, min=1
item_tiers[ending_unit][0..n]
The highest value in the quantity tier.
optional, integer
item_tiers[price][0..n]
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.
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
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.
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
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.
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
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.
optional, string, max chars=33
+
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]
The amount to be charged. The unit depends on the type of currency.
optional, in cents, min=1
charges[amount_in_decimal][0..n]
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.
optional, string, max chars=33
charges[description][0..n]
Description for this charge.
optional, string, max chars=250
charges[taxable][0..n]

optional, boolean, default=true
charges[tax_profile_id][0..n]
Tax profile of the charge.
optional, string, max chars=50
charges[avalara_tax_code][0..n]
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.
optional, string, max chars=50
charges[taxjar_product_code][0..n]
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, string, max chars=50
charges[avalara_sale_type][0..n]
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.
charges[avalara_transaction_type][0..n]
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.
optional, integer
charges[avalara_service_type][0..n]
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.
optional, integer
charges[date_from][0..n]
The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds
charges[date_to][0..n]
The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds
Resource object representing hosted_page.
always returned

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

The following steps describe how best to use this API:

  1. Call this endpoint, providing item prices, coupons and a host of other details such as billing and shipping addresses to be prefilled for the customer on the checkout page.
  2. Send the customer to the Checkout url received in the response.
  3. Once they complete checkout, a new subscription is automatically created and the customer is redirected to the redirect_url with the id and state attributes passed as query string parameters.
  4. Retrieve the hosted page at this stage to get the subscription and invoice details.

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 ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/hosted_pages/checkout_new_for_items
billing_cycles
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.
optional, integer, min=0
mandatory_items_to_remove[0..n]
Item ids of mandatorily attached addons that are to be removed from the subscription.
optional, list of string
terms_to_charge
The number of subscription billing cycles (including the first one) to invoice in advance.
optional, integer, min=1
billing_alignment_mode
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.
optional, enumerated string
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]
List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.
optional, list of string
redirect_url
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 :
  • 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.
    optional, string, max chars=250
cancel_url
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.
    optional, string, max chars=250
pass_thru_content
You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.
optional, string, max chars=2048
allow_offline_payment_methods
Allow the customer to select an offline payment method during checkout. The choice of payment methods can be configured via the Chargebee UI.
optional, boolean
+
subscription
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[id]
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
optional, string, max chars=50
subscription[trial_end]
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.
optional, timestamp(UTC) in seconds
subscription[start_date]
The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately. If set to a value in the past then that date/time should not be more than a plan billing period into the past.
optional, timestamp(UTC) in seconds
subscription[coupon]

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.

optional, string, max chars=50
subscription[auto_collection]
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
optional, enumerated string
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]
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.
optional, string, max chars=2000
subscription[contract_term_billing_cycle_on_renewal]
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.
optional, integer, min=1, max=100
subscription[affiliate_token]
A unique tracking token.
optional, string, max chars=250
+
customer
Parameters for customer
pass parameters as customer[<param name>]
customer[id]
Id for the new customer. If not given, this will be same as the subscription id.
optional, string, max chars=50
customer[email]
Email of the customer. Configured email notifications will be sent to this email.
optional, string, max chars=70
customer[first_name]
First name of the customer. If not provided it will be got from contact information entered in the hosted page .
optional, string, max chars=150
customer[last_name]
Last name of the customer. If not provided it will be got from contact information entered in the hosted page .
optional, string, max chars=150
customer[company]
Company name of the customer.
optional, string, max chars=250
customer[taxability]
Specifies if the customer is liable for tax.
optional, enumerated string, default=taxable
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]
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.
optional, string, max chars=50
customer[phone]
Phone number of the customer.
optional, string, max chars=50
customer[vat_number]
VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20
customer[vat_number_prefix]
VAT/ Tax registration number prefix of the customer. Learn more.
optional, string, max chars=10
+
card
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
billing_address[email]
The email address.
optional, string, max chars=70
billing_address[company]
The company name.
optional, string, max chars=250
billing_address[phone]
The phone number.
optional, string, max chars=50
billing_address[line1]
Address line 1.
optional, string, max chars=150
billing_address[line2]
Address line 2.
optional, string, max chars=150
billing_address[line3]
Address line 3.
optional, string, max chars=150
billing_address[city]
The name of the city.
optional, string, max chars=50
billing_address[state_code]
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).
optional, string, max chars=50
billing_address[state]
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50
billing_address[zip]
Zip or Postal code.
optional, string, max chars=20
billing_address[country]
2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
shipping_address[email]
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
shipping_address[phone]
The phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
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).
optional, string, max chars=50
shipping_address[state]
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
+
contract_term
Parameters for contract_term
pass parameters as contract_term[<param name>]
contract_term[action_at_term_end]
Action to be taken when the contract term completes.
optional, enumerated string, default=cancel
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]
    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.
    optional, integer, default=0
    +
    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]
    The unique identifier of the item price.
    required, string, max chars=100
    subscription_items[quantity][0..n]
    The quantity of the item purchased.
    optional, integer, min=1
    subscription_items[quantity_in_decimal][0..n]
    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.
    optional, string, max chars=33
    subscription_items[unit_price][0..n]
    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.
    optional, in cents, min=0
    subscription_items[unit_price_in_decimal][0..n]
    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.
    optional, string, max chars=33
    subscription_items[billing_cycles][0..n]
    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.
    optional, integer, min=0
    subscription_items[trial_end][0..n]
    The date/time when the trial period of the item ends. Applies to plan-items and—-when enabled-—addon-items as well.
    optional, timestamp(UTC) in seconds
    subscription_items[service_period_days][0..n]
    The service period of the item in days from the day of charge.
    optional, integer, min=1, max=730
    subscription_items[charge_on_event][0..n]
    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.
    optional, enumerated string
    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]
    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.
    optional, boolean
    subscription_items[charge_on_option][0..n]
    Indicates when the charge-item is to be charged. This parameter only applies to charge-items.
    optional, enumerated string
    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.
    +
    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]
    The id of the item price for which the tier price is being overridden.
    optional, string, max chars=100
    item_tiers[starting_unit][0..n]
    The lowest value in the quantity tier.
    optional, integer, min=1
    item_tiers[ending_unit][0..n]
    The highest value in the quantity tier.
    optional, integer
    item_tiers[price][0..n]
    The overridden price of the tier. The value depends on the type of currency.
    optional, in cents, default=0, min=0
    item_tiers[starting_unit_in_decimal][0..n]
    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.
    optional, string, max chars=33
    item_tiers[ending_unit_in_decimal][0..n]
    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.
    optional, string, max chars=33
    item_tiers[price_in_decimal][0..n]
    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.
    optional, string, max chars=33
    Resource object representing hosted_page.
    always returned

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

    The following steps describe how best to use this API:

    1. 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.
    2. Send the customer to the Checkout url received in the response. They can now add a payment method or use an existing one, to complete the checkout.
    3. The subscription is updated and the customer is redirected to the redirect_url with the id and state attributes passed as query string parameters.
    4. 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 ]

    Show more...
    {"hosted_page": { "created_at": 1517478504, "embed": false, "expires_at": 1517482104, "id": "__test__lxYzKMHM7UcueYo6mZabybQOacdfXv7LtV", "object": "hosted_page", "resource_version": 1517478504000, "state": "created", "type": "checkout_existing", "updated_at": 1517478504, "url": "https://yourapp.chargebee.com/pages/v3/__test__lxYzKMHM7UcueYo6mZabybQOacdfXv7LtV/" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/checkout_existing_for_items
    mandatory_items_to_remove[0..n]
    Item ids of mandatorily attached addons that are to be removed from the subscription.
    optional, list of string
    replace_items_list
    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.
    optional, boolean
    billing_cycles
    Billing cycles set for plan-item price is used by default.
    optional, integer, min=0
    terms_to_charge
    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.
    optional, integer, min=1
    reactivate_from
    When the subscription is reactivated as described under the reactivate parameter, this is the date/time at which the subscription should be reactivated.
    optional, timestamp(UTC) in seconds
    billing_alignment_mode
    Override the billing alignment mode chosen for the site for calendar billing. Only applicable when using calendar billing.
    optional, enumerated string
    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]
    List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.
    optional, list of string
    reactivate
    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.
    optional, boolean
    force_term_reset
    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.
    optional, boolean, default=false
    redirect_url
    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 :
    • 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.
      optional, string, max chars=250
    cancel_url
    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.
      optional, string, max chars=250
    pass_thru_content
    You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.
    optional, string, max chars=2048
    allow_offline_payment_methods
    Allow the customer to select an offline payment method during checkout. The choice of payment methods can be configured via the Chargebee UI.
    optional, boolean
    +
    subscription
    Parameters for subscription
    pass parameters as subscription[<param name>]
    subscription[id]
    A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
    required, string, max chars=50
    subscription[start_date]
    The new start date of a future subscription. Applicable only for future subscriptions.
    optional, timestamp(UTC) in seconds
    subscription[trial_end]
    This overrides trial period set for the plan-item. Set it to 0 to have no trial period.
    optional, timestamp(UTC) in seconds
    subscription[auto_collection]
    Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
    optional, enumerated string
    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[offline_payment_method]
    The preferred offline payment method for the subscription.
    optional, enumerated string
    Possible values are
    no_preferenceNo Preference.cashCash.checkCheck.bank_transferBank Transfer.ach_creditACH Credit.sepa_creditSEPA Credit.
    subscription[invoice_notes]
    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.
    optional, string, max chars=2000
    subscription[contract_term_billing_cycle_on_renewal]
    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.
    optional, integer, min=1, max=100
    +
    customer
    Parameters for customer
    pass parameters as customer[<param name>]
    customer[vat_number]
    VAT/ Tax registration number of the customer. Learn more.
    optional, string, max chars=20
    customer[vat_number_prefix]
    VAT/ Tax registration number prefix of the customer. Learn more.
    optional, string, max chars=10
    +
    card
    Parameters for card
    pass parameters as card[<param name>]
    card[gateway_account_id]
    The gateway account in which this payment source is stored.
    optional, string, max chars=50
    +
    contract_term
    Parameters for contract_term
    pass parameters as contract_term[<param name>]
    contract_term[action_at_term_end]
    Action to be taken when the contract term completes.
    optional, enumerated string, default=cancel
    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]
    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.
    optional, integer, default=0
    +
    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]
    The unique identifier of the item price.
    required, string, max chars=100
    subscription_items[quantity][0..n]
    The quantity of the item purchased.
    optional, integer, min=1
    subscription_items[quantity_in_decimal][0..n]
    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.
    optional, string, max chars=33
    subscription_items[unit_price][0..n]
    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.
    optional, in cents, min=0
    subscription_items[unit_price_in_decimal][0..n]
    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.
    optional, string, max chars=33
    subscription_items[billing_cycles][0..n]
    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.
    optional, integer, min=0
    subscription_items[trial_end][0..n]
    The date/time when the trial period of the item ends. Applies to plan-items and—-when enabled-—addon-items as well.
    optional, timestamp(UTC) in seconds
    subscription_items[service_period_days][0..n]
    The service period of the item in days from the day of charge.
    optional, integer, min=1, max=730
    subscription_items[charge_on_event][0..n]
    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.
    optional, enumerated string
    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]
    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.
    optional, boolean
    subscription_items[charge_on_option][0..n]
    Indicates when the charge-item is to be charged. This parameter only applies to charge-items.
    optional, enumerated string
    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.
    +
    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]
    The id of the item price for which the tier price is being overridden.
    optional, string, max chars=100
    item_tiers[starting_unit][0..n]
    The lowest value in the quantity tier.
    optional, integer, min=1
    item_tiers[ending_unit][0..n]
    The highest value in the quantity tier.
    optional, integer
    item_tiers[price][0..n]
    The overridden price of the tier. The value depends on the type of currency.
    optional, in cents, min=0
    item_tiers[starting_unit_in_decimal][0..n]
    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.
    optional, string, max chars=33
    item_tiers[ending_unit_in_decimal][0..n]
    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.
    optional, string, max chars=33
    item_tiers[price_in_decimal][0..n]
    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.
    optional, string, max chars=33
    Resource object representing hosted_page.
    always returned

    Note: If you're using Checkout V3, 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 ]

    Show more...
    {"hosted_page": { "created_at": 1517506020, "embed": true, "expires_at": 1517592420, "id": "__test__Rvi8fL7SS0CURBeH2k0CgkPLH6MyU2Sy", "object": "hosted_page", "resource_version": 1517506020000, "state": "created", "type": "update_payment_method", "updated_at": 1517506020, "url": "https://yourapp.chargebee.com/pages/v2/__test__Rvi8fL7SS0CURBeH2k0CgkPLH6MyU2Sy/update_payment_method" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/update_payment_method
    redirect_url
    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 :
    • 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.
      optional, string, max chars=250
    cancel_url
    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.
      optional, string, max chars=250
    pass_thru_content
    You can pass through any content specific to the hosted page request and get it back after user had submitted the hosted page.
    optional, string, max chars=2048
    iframe_messaging
    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.
    optional, boolean, default=false
    +
    customer
    Parameters for customer
    pass parameters as customer[<param name>]
    customer[id]
    Identifier of the customer.
    required, string, max chars=50
    +
    card
    Parameters for card
    pass parameters as card[<param name>]
    card[gateway_account_id]
    The gateway account in which this payment source is stored.
    optional, string, max chars=50
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517506015, "embed": false, "expires_at": 1517592415, "id": "__test__LycuLPCkhW3axOiXjHWkOOVl3ZE3yLLni", "object": "hosted_page", "resource_version": 1517506015000, "state": "created", "type": "manage_payment_sources", "updated_at": 1517506015, "url": "https://yourapp.chargebee.com/pages/v3/__test__LycuLPCkhW3axOiXjHWkOOVl3ZE3yLLni/" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/manage_payment_sources
    redirect_url
    URL to redirect after payment method is added.
    optional, string, max chars=250
    +
    customer
    Parameters for customer
    pass parameters as customer[<param name>]
    customer[id]
    Identifier of the customer.
    required, string, max chars=50
    +
    card
    Parameters for card
    pass parameters as card[<param name>]
    card[gateway_account_id]
    The gateway account in which this payment source is stored.
    optional, string, max chars=50
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517506010, "embed": true, "expires_at": 1517592410, "id": "__test__4cq9mwW1cuoD085nSBLh0KUMKdphVO5cC", "object": "hosted_page", "resource_version": 1517506010000, "state": "created", "type": "collect_now", "updated_at": 1517506010, "url": "https://yourapp.chargebee.com/pages/v3/__test__4cq9mwW1cuoD085nSBLh0KUMKdphVO5cC/collect_now" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/collect_now
    redirect_url
    URL to redirect after invoices are paid.
    optional, string, max chars=250
    currency_code
    The currency code (ISO 4217 format) of the specified credit amount.
    optional, string, max chars=3
    +
    customer
    Parameters for customer
    pass parameters as customer[<param name>]
    customer[id]
    Identifier of the customer.
    required, string, max chars=50
    +
    card
    Parameters for card
    pass parameters as card[<param name>]
    card[gateway_account_id]
    The gateway account in which this payment source is stored.
    optional, string, max chars=50
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517505980, "embed": true, "expires_at": 1517596199, "id": "__test__IKNpcdSoRFV0hFeci8SSkUbhZYjle2dKh", "object": "hosted_page", "resource_version": 1517505981000, "state": "created", "type": "checkout_existing", "updated_at": 1517505981, "url": "https://yourapp.chargebee.com/pages/v2/__test__IKNpcdSoRFV0hFeci8SSkUbhZYjle2dKh/checkout" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/accept_quote
    redirect_url
    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 :
    • 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.
      optional, string, max chars=250
    +
    quote
    Parameters for quote
    pass parameters as quote[<param name>]
    quote[id]
    The quote number. Acts as a identifier for quote and typically generated sequentially.
    required, string, max chars=50
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517506012, "embed": true, "expires_at": 1518715612, "id": "__test__Bct8ySC6A1eV2GdMcdUl7dzovgyKhAz4M", "object": "hosted_page", "resource_version": 1517506012000, "state": "created", "type": "extend_subscription", "updated_at": 1517506012, "url": "https://yourapp.chargebee.com/pages/v3/__test__Bct8ySC6A1eV2GdMcdUl7dzovgyKhAz4M/" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/extend_subscription
    expiry
    Expiry (in days) for the link generated. No expiry will be set if this is not specified.
    optional, integer, min=1, max=500
    billing_cycle
    Number of billing cycles to extend. If not specified, plan's billing cycle will be used.
    optional, integer, min=1
    +
    subscription
    Parameters for subscription
    pass parameters as subscription[<param name>]
    subscription[id]
    A unique and immutable identifier for the subscription. If not provided, it is autogenerated.
    required, string, max chars=50
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517484798, "embed": false, "expires_at": 1517488398, "id": "__gift___test__gPY4LqKkoEdrcdWdxpl6nABSZu2oDcCpR", "object": "hosted_page", "resource_version": 1517484798645, "state": "created", "type": "checkout_gift", "updated_at": 1517484798, "url": "https://yourapp.chargebee.com/pages/v3/__gift___test__gPY4LqKkoEdrcdWdxpl6nABSZu2oDcCpR/" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items
    redirect_url
    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 :
    • 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.
      optional, string, max chars=250
    coupon_ids[0..n]
    List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.
    optional, list of string
    +
    gifter
    Parameters for gifter
    pass parameters as gifter[<param name>]
    gifter[customer_id]
    Gifter customer id.
    optional, string, max chars=50
    gifter[locale]
    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.
    optional, string, max chars=50
    +
    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]
    The unique identifier of the item price.
    optional, string, max chars=100
    subscription_items[quantity][0..n]
    The quantity of the item purchased.
    optional, integer, default=1, min=1
    subscription_items[quantity_in_decimal][0..n]
    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.
    optional, string, max chars=33
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517678804, "embed": false, "expires_at": 1517682404, "id": "__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd", "object": "hosted_page", "resource_version": 1517678804000, "state": "created", "type": "claim_gift", "updated_at": 1517678804, "url": "https://yourapp.chargebee.com/pages/v3/__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd/claim_gift" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/claim_gift
    redirect_url
    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 :
    • 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.
      optional, string, max chars=250
    +
    gift
    Parameters for gift
    pass parameters as gift[<param name>]
    gift[id]
    Uniquely identifies a gift.
    required, string, max chars=150
    +
    customer
    Parameters for customer
    pass parameters as customer[<param name>]
    customer[locale]
    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.
    optional, string, max chars=50
    Resource object representing hosted_page.
    always returned

    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 ]

    Show more...
    {"hosted_page": { "created_at": 1517506018, "embed": false, "expires_at": 1520098018, "id": "__test__AUCK2LNxny5cXiA1JcdBQE9283e5McdvCC", "object": "hosted_page", "resource_version": 1517506018000, "state": "created", "type": "agreement_pfd", "updated_at": 1517506018, "url": "https://yourapp.chargebee.com/action_pages/__test__AUCK2LNxny5cXiA1JcdBQE9283e5McdvCC/agreement_pdf" }}

    URL Format POST

    https://{site}.chargebee.com/api/v2/hosted_pages/retrieve_agreement_pdf
    payment_source_id
    Payment source to be used for this payment.
    required, string, max chars=40
    Resource object representing hosted_page.
    always returned
    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
    Resource object representing hosted_page.
    always returned

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

    Show more...
    {"hosted_page": { "created_at": 1517506016, "embed": true, "expires_at": 1517509616, "id": "__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r", "object": "hosted_page", "resource_version": 1517506016000, "state": "created", "type": "checkout_existing", "updated_at": 1517506016, "url": "https://yourapp.chargebee.com/pages/v2/__test__Mgd44pMvDRJLhuy3KNs2j6qBRNbuGG9r/checkout" }}

    URL Format GET

    https://{site}.chargebee.com/api/v2/hosted_pages/{hosted_page_id}
    Resource object representing hosted_page.
    always returned
    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 ]

    Show more...
    { "list": [ {"hosted_page": { "created_at": 1517678804, "embed": false, "expires_at": 1517682404, "id": "__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd", "object": "hosted_page", "resource_version": 1517678804000, "state": "created", "type": "claim_gift", "updated_at": 1517678804, "url": "https://yourapp.chargebee.com/pages/v3/__test__yRVH4Pr8siRXJEPsjeJXlcd8Aq1fDqVzd/claim_gift" }}, {..} ], "next_offset": "[\"1517506012000\",\"186000000018\"]" }

    URL Format GET

    https://{site}.chargebee.com/api/v2/hosted_pages
    limit
    The number of resources to be returned.
    optional, integer, default=10, min=1, max=100
    offset
    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.
    optional, string, max chars=1000
    Filter Params
    For operator usages, see the Pagination and Filtering section.
    id[<operator>]
    Unique identifier generated for each hosted page requested.
    Supported operators : is, is_not, starts_with, in, not_in

    Example id[is] = "Edi69nxpu6BeGBd9Fjcd0tqCSwb0sRcuKa"
    optional, string filter
    type[<operator>]
    Type of the requested hosted page. Possible values are : checkout_new, checkout_existing, update_payment_method, manage_payment_sources, collect_now, extend_subscription, checkout_gift, claim_gift, checkout_one_time.
    Supported operators : is, is_not, in, not_in

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

    Example state[is] = "succeeded"
    optional, enumerated string filter
    updated_at[<operator>]
    Timestamp indicating when this hosted page was last updated.
    Supported operators : after, before, on, between

    Example updated_at[on] = "1490784813"
    optional, timestamp(UTC) in seconds filter
    Resource object representing hosted_page.
    always returned
    next_offset
    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”.
    optional, string, max chars=1000