Pricing page sessions

API Version

Product Catalog

Library

The pricing_page_session resource allows you to create a pricing page that incorporates customer and subscription details. This page helps customers choose a plan, start a new subscription, or modify an existing one. Each session is distinct and has a limited duration, ensuring a unique and time-sensitive experience.

Sample pricing page session [ JSON ]

{
    "id": "__test__VZlifqcdrl4Itq1go1b5lZY5cu2OJYYaNp",
    "url": "https://hosted.atomicpricing.com/sites/01HTPJMZXNJ2CGQ9FP6W2BJA9B/pricing-session/__test__VZlifqcdrl4Itq1go1b5lZY5cu2OJYYaNp",
    "created_at": 1709792318,
    "expires_at": 1709795918,
    "object": "pricing_page_session"
}

id

optional, string, max chars=70
Unique identifier generated for each pricing page session requested.

url

optional, string, max chars=250
Unique URL for the pricing page that can be included in your website.

created_at

optional, timestamp(UTC) in seconds
Indicates when this pricing page session is generated.

expires_at

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

This endpoint streamlines the generation of a pricing page session to enable new subscription creation workflows using Chargebee's hosted pricing pages (Atomic Pricing). By providing a subscription ID and/or customer ID as a parameter, you'll obtain a pricing page session URL.

Note: Full access key authentication is needed for this API request.

Sample Request

curl  https://{site}.chargebee.com/api/v2/pricing_page_sessions/create_for_new_subscription \
     -u {site_api_key}:\
     -d "pricing_page[id]"="01HTPJN1JKBQ3BQ3ZH7V8X2Z9Q" \
     -d "subscription[id]"="__test__KyVnHhSBWmCoF2tJ" \
     -d "customer[id]"="__test__8asqlU6yBgeA3k"

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/pricing_page_sessions/create_for_new_subscription \
     -u {site_api_key}:\
     -d "pricing_page[id]"="01HTPJN1JKBQ3BQ3ZH7V8X2Z9Q" \
     -d "subscription[id]"="__test__KyVnHhSBWmCoF2tJ" \
     -d "customer[id]"="__test__8asqlU6yBgeA3k"

Sample Response [ JSON ]

{
    "pricing_page_session": {
        "id": "__test__VZlifqcdrl4Itq1go1b5lZY5cu2OJYYaNp",
        "url": "https://hosted.atomicpricing.com/sites/01HTPJMZXNJ2CGQ9FP6W2BJA9B/pricing-session/__test__VZlifqcdrl4Itq1go1b5lZY5cu2OJYYaNp",
        "created_at": 1709792318,
        "expires_at": 1709795918,
        "object": "pricing_page_session"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/pricing_page_sessions/create_for_new_subscription

redirect_url[]

optional, string, max chars=250
The customers will be redirected to this URL upon successful checkout.

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, new subscription and customer resources are created within the business entity.

pricing_page

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

pricing_page[id]

required, string, max chars=50
The unique identifier of the pricing page for which the hosted pricing page is created.

subscription

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

subscription[id]

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

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. When not provided, a new customer is created with the ID set to the value provided for subscription[id]. If subscription[id] is unavailable, then the customer ID is autogenerated.

customer[email]

optional, string, max chars=70
Email of the customer. Configured email notifications will be sent to this email.

customer[first_name]

optional, string, max chars=150
First name of the customer. If not provided it will be got from contact information entered in the hosted page

customer[last_name]

optional, string, max chars=150
Last name of the customer. If not provided it will be got from contact information entered in the hosted page

customer[company]

optional, string, max chars=250
Company name of the customer.

customer[phone]

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

customer[locale]

optional, string, max chars=50
Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.

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

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]

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

Note:

This enum value is not supported for pricing_page_sessions resource, soon this value will be available for this resource. For more details please reach out to atomic-pricing@chargebee.com

specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.

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.

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 you want to use for a discount. This is only applicable when 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 is specific_item_price.

discounts[label][0..n]

optional, string, max chars=100
Label for the discount

pricing_page_session

always returned
Resource object representing pricing_page_session

This endpoint streamlines the generation of a pricing page session to enable subscription upgrade, and downgrade workflows using Chargebee's hosted pricing pages (Atomic Pricing). By providing a subscription ID as a parameter, you will obtain a hosted pricing page session URL.

Note: Full access key authentication is needed for this API request.

Sample Request

curl  https://{site}.chargebee.com/api/v2/pricing_page_sessions/create_for_existing_subscription \
     -u {site_api_key}:\
     -d "pricing_page[id]"="01HTPJN1JKBQ3BQ3ZH7V8X2Z9Q" \
     -d "subscription[id]"="__test__KyVnHhSBWmCoF2tJ"

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/pricing_page_sessions/create_for_existing_subscription \
     -u {site_api_key}:\
     -d "pricing_page[id]"="01HTPJN1JKBQ3BQ3ZH7V8X2Z9Q" \
     -d "subscription[id]"="__test__KyVnHhSBWmCoF2tJ"

Sample Response [ JSON ]

{
    "pricing_page_session": {
        "id": "__test__VZlifqcdrl4Itq1go1b5lZY5cu2OJYYaNp",
        "url": "https://hosted.atomicpricing.com/sites/01HTPJMZXNJ2CGQ9FP6W2BJA9B/pricing-session/__test__VZlifqcdrl4Itq1go1b5lZY5cu2OJYYaNp",
        "created_at": 1709792318,
        "expires_at": 1709795918,
        "object": "pricing_page_session"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/pricing_page_sessions/create_for_existing_subscription

redirect_url[]

optional, string, max chars=250
The customers will be redirected to this URL upon successful checkout.

pricing_page

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

pricing_page[id]

required, string, max chars=50
The unique identifier of the pricing page for which the hosted pricing page is created.

subscription

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

subscription[id]

required, string, max chars=50
The unique identifier of an existing subscription for which the hosted pricing page is created.

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]

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

Note:

This enum value is not supported for pricing_page_sessions resource, soon this value will be available for this resource. For more details please reach out to atomic-pricing@chargebee.com

specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.

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

discounts[percentage][0..n]

optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.

discounts[amount][0..n]

optional, in cents, min=0
The value of the discount. The format of this value depends on the kind of currency you want to use for a discount. This is only applicable when 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[label][0..n]

optional, string, max chars=100
Label for the discount

pricing_page_session

always returned
Resource object representing pricing_page_session

Sample pricing page session [ JSON ]

API Index URL GET

Model Class

Pricing page session attributes

Consent Fields for Pricing page session

Custom Fields for Pricing page session

Create pricing page for new subscription ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create pricing page for existing subscription ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL