ChargebeeAPI

Create checkout for a new subscription

Idempotency Supported
Try in API Explorer

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. You may also provide pass_thru_content containing information and IDs from your systems that must be associated with the checkout page.

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

  • Send the customer to the Checkout url received in the response.
  • 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 an autogenarated ID and the subscription is created under it.

Multiple business entities

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

Billing address editing

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

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

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

Sample Request

URL Format

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

Input Parameters

layout
optional, enumerated string

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

Possible Enum Values
in_app

Indicates in-app checkout version

full_page

Indicates full page checkout version

business_entity_id
optional, string, max chars=50

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

Note

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

See also

Customer resource lookup and creation.
billing_cycles
optional, integer, min=0

The number of billing cycles the subscription runs before canceling. If not provided, then the billing cycles set for the plan-item price is used.

mandatory_items_to_remove
optional, 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 Enum Values
immediate

Subscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..

delayed

Subscription period will be aligned with the configured billing date at the next renewal.

coupon_ids
optional, string

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

redirect_url
optional, string, max chars=250

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

Note :

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

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

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

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

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

allow_offline_payment_methods
optional, boolean

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

subscription
optional, string

Parameters for subscription

customer
optional, string

Parameters for customer

card
optional, string

Parameters for card

billing_address
optional, string

Parameters for billing_address

shipping_address
optional, string

Parameters for shipping_address

contract_term
optional, enumerated string

Parameters for contract_term

subscription_items
optional, string

Parameters for subscription_items

discounts
optional, enumerated string

Parameters for discounts

item_tiers
optional, string

Parameters for item_tiers

entity_identifiers
optional, string

Parameters for entity_identifiers

Returns

hosted_pageHosted page object

Resource object representing hosted_page