Upgrading to Product Catalog 2.0

If you are using Chargebee API v2, this document provides detailed mapping information for upgrading from Product Catalog 1.0 to Product Catalog 2.0.

Resources

The table below shows how the primary API resources or objects in Product Catalog 1.0 map to those in Product Catalog 2.0. Some resources in the latter are newly introduced and have no equivalents in the former.

Product Catalog 1.0	Product Catalog 2.0
N/A	Item Families
Plans	Items Item Prices Attached items
Addons	Items Item Prices Attached items
N/A	Differential Prices
N/A	Usages

Endpoints

Each of the tables in this section maps the various endpoints in Product Catalog 1.0 to their corresponding equivalents in Product Catalog 2.0.

Note

This section does not list the endpoints that have no change from Product Catalog 1.0 to 2.0.

Plans

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/plans`	`POST` `/api/v2/items` `POST` `/api/v2/item_prices` `POST` `/v2/items/{item_id}/attached_items`
`POST` `/api/v2/plans/{plan_id}`	`POST` `/api/v2/items/{item_id}` `POST` `/api/v2/item_prices/{item_price_id}` `POST` `/api/v2/attached_items/{attached_item_id}`
`GET` `/api/v2/plans/{planId}`	`GET` `/api/v2/items/{item_id}/` `GET` `/api/v2/item_prices/{item_price_id}`
`GET` `/api/v2/plans`	`GET` `/api/v2/items` `GET` `/api/v2/item_prices`

Addons

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/addons`	`POST` `/api/v2/items` `POST` `/api/v2/item_prices`
`POST` `/api/v2/addons/{addon_id}`	`POST /api/v2/items/{item_id}` `POST /api/v2/item_prices/{item_price_id}`
`GET` `/api/v2/addon/{addon_id}`	`GET` `/api/v2/items/{item_id}` `GET` `/api/v2/item_prices/{item_price_id}`
`GET` `/api/v2/addon/`	`GET` `/api/v2/items` `GET` `/api/v2/item_prices`

Coupons

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/coupons`	`POST` `/api/v2/coupons/create_for_items`
`POST` `/api/v2/coupons/{coupon_id}`	`POST` `/v2/coupons/{coupon_id}/update_for_items`

Subscriptions

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/subscriptions`	`POST` `/api/v2/customers/{customer_id}/subscription_for_items`
`POST` `/api/v2/customers/{customer_id}/subscriptions`	`POST` `/api/v2/customers` `POST` `/api/v2/customers/{customer_id}/subscription_for_items`
`POST` `/api/v2/subscriptions/{subscription_id}`	`POST` `/v2/subscriptions/{subscription_id}/update_for_items`
`GET` `/api/v2/subscriptions/{subscription_id}`	`GET` `/api/v2/subscriptions/{subscription_id}`
`POST` `/api/v2/subscriptions/{subscription_id}/cancel`	`POST` `/api/v2/subscriptions/{subscription_id}/cancel_for_items`

Invoices

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/invoices`	`POST` `/api/v2/invoices/create_for_charge_items_and_charges`
`POST` `/api/v2/invoices/charge_addon`	`POST`* *`/api/v2/invoices/create_for_charge_item`
`POST` `/api/v2/invoices/{invoice_id}/add_charge`	`POST` `/api/v2/invoices/{invoice_id}/add_charge`
`POST` `/api/v2/invoices/{invoice_id}/add_addon_charge`	`POST` `/api/v2/invoices/{invoice_id}/add_charge_item`

Quotes

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/customers/{customer_id}/create_subscription_quote`	`POST` `/api/v2/customers/{customer_id}/create_subscription_quote_for_items`
`POST` `/api/v2/quotes/{quote_id}/edit_create_subscription_quote`	`POST` `/api/v2/quotes/{quote_id}/edit_create_subscription_quote_for_items`
`POST` `/api/v2/quotes/update_subscription_quote``	`POST` `/api/v2/quotes/update_subscription_quote_for_items`
`POST` `/api/v2/quotes/{quote_id}/edit_update_subscription_quote`	`POST` `/api/v2/quotes/{quote_id}/edit_update_subscription_quote_for_items`
`POST` `/api/v2/quotes/create_for_onetime_charges`	`POST` `/api/v2/quotes/create_for_charge_items_and_charges`
`POST` `/api/v2/quotes/{quote_id}/edit_one_time_quote`	`POST` `/api/v2/quotes/{quote_id}/edit_for_charge_items_and_charges`

Gifts

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/gifts`	`POST` `/api/v2/gifts/create_for_items`

Hosted Pages

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/hosted_pages/checkout_new`	`POST` `/api/v2/hosted_pages/checkout_new_for_items`
`POST` `/api/v2/hosted_pages/checkout_existing`	`POST` `/api/v2/hosted_pages/checkout_existing_for_items`
`POST` `/api/v2/hosted_pages/checkout_one_time`	`POST` `/api/v2/hosted_pages/checkout_one_time_for_items`
`POST` `/api/v2/hosted_pages/checkout_gift`	`POST` `/api/v2/hosted_pages/checkout_gift_for_items`

Estimates

Product Catalog 1.0	Product Catalog 2.0
`POST` `/api/v2/estimates/create_subscription`	`POST` `/api/v2/estimates/create_subscription_for_items`
`GET` `/api/v2/customers/{customer_id}/create_subscription_estimate`	`POST` `/api/v2/customers/{customer_id}/create_subscription_for_items_estimate`
`POST` `/api/v2/estimates/update_subscription`	`POST` `/api/v2/estimates/update_subscription_for_items`
`POST` `/api/v2/subscriptions/{subscription_id}/cancel_subscription_estimate`	`POST` `/api/v2/subscriptions/{subscription_id}/cancel_subscription_for_items_estimate`
`POST` `/api/v2/estimates/gift_subscription`	`POST` `/api/v2/estimates/gift_subscription_for_items`
`POST` `/api/v2/estimates/create_invoice`	`POST` `/api/v2/estimates/create_invoice_for_items`

Parameters

The tables in this section map the individual input parameters for endpoints from Product Catalog 1.0 to their Product Catalog 2.0 equivalents.

Plans

Create a plan

Product Catalog 1.0	Product Catalog 2.0
Create a plan `POST` `/api/v2/plans`	Create an item `POST` `/api/v2/items`
`id`	`id`
`name`	`name`
`description`	`description`
`status`	Not passed as input for this endpoint.
`is_shippable`	`is_shippable`
`is_giftable`	`is_giftable`
`redirect_url`	`redirect_url`
`enabled_in_hosted_pages`	`enabled_for_checkout`
`enabled_in_portal`	`enabled_in_portal`
`addon_applicability`	`item_applicability`
`applicable_addons[id][0..n]`	`applicable_items[0..n]`
N/A	`type` = `plan`
`claim_url`	`gift_claim_redirect_url`
""	"Create an item price" `POST` `/api/v2/item_prices`
N/A	`id`
N/A	`name`
N/A	`description`
`invoice_name`	`external_name`
`trial_period`	`trial_period`
`trial_period_unit`	`trial_period_unit`
`period`	`period`
`period_unit`	`period_unit`
`setup_cost`	N/A
`price`	`price`
`currency_code`	`currency_code`
`billing_cycles`	`billing_cycles`
`pricing_model`	`pricing_model`
`free_quantity`	`free_quantity`
`taxable`	`is_taxable`
`tax_profile_id`	`tax_detail[tax_profile_id]`
`tax_code`	`tax_detail[avalara_tax_code]`
`taxjar_product_code`	`tax_detail[taxjar_product_code]`
`avalara_sale_type`	`tax_detail[avalara_sale_type]`
`avalara_transaction_type`	`tax_detail[avalara_transaction_type]`
`avalara_service_type`	`tax_detail[avalara_service_type]`
`sku`	`accounting_detail[sku]`
`accounting_code`	`accounting_detail[accounting_code]`
`accounting_category1`	`accounting_detail[accounting_category1]`
`accounting_category2`	`accounting_detail[accounting_category2]`
`accounting_category3`	`accounting_detail[accounting_category3]`
`accounting_category4`	`accounting_detail[accounting_category4]`
`shipping_frequency_period`	`shipping_period`
`shipping_frequency_period_unit`	`shipping_period_unit`
`invoice_notes`	`invoice_notes`
`meta_data`	`metadata`
`tiers[starting_unit][0..n]`	`tiers[starting_unit][0..n]`
`tiers[ending_unit][0..n]`	`tiers[ending_unit][0..n]`
`tiers[price][0..n]`	`tiers[price][0..n]`

Addons

Create an addon

Product Catalog 1.0	Product Catalog 2.0
Create an addon `POST` `/api/v2/addons`	Create an item `POST` `/api/v2/items`
`id`	`id`
`name`	`name`
`description`	`description`
`enabled_in_portal`	`enabled_in_portal`
`charge_type` = `recurring`	`type` = `addon`
`charge_type` = `non_recurring`	`type` = `charge`
`is_shippable`	`is_shippable`
`status`	Not passed as input for this endpoint.
""	"Create an item price" `POST` `/api/v2/item_prices`
N/A	`id`
N/A	`name`
N/A	`description`
`invoice_name`	`external_name`
`price`	`price`
`currency_code`	`currency_code`
`period`	`period` (Applicable only when `item.type` = `addon`)
`period_unit`	`period_unit` (Applicable only when `item.type` = `addon`)
`billing_cycles`	`billing_cycles`
`unit`	`unit`
`pricing_model`	`pricing_model`
`taxable`	`is_taxable`
`tax_profile_id`	`tax_detail[tax_profile_id]`
`tax_code`	`tax_detail[avalara_tax_code]`
`taxjar_product_code`	`tax_detail[taxjar_product_code]`
`avalara_sale_type`	`tax_detail[avalara_sale_type]`
`avalara_transaction_type`	`tax_detail[avalara_transaction_type]`
`avalara_service_type`	`tax_detail[avalara_service_type]`
`sku`	`accounting_detail[sku]`
`accounting_code`	`accounting_detail[accounting_code]`
`accounting_category1`	`accounting_detail[accounting_category1]`
`accounting_category2`	`accounting_detail[accounting_category2]`
`accounting_category3`	`accounting_detail[accounting_category3]`
`accounting_category4`	`accounting_detail[accounting_category4]`
`shipping_frequency_period`	`shipping_period`
`shipping_frequency_period_unit`	`shipping_period_unit`
`invoice_notes`	`invoice_notes`
`meta_data`	`metadata`
`tiers[starting_unit][0..n]`	`tiers[starting_unit][0..n]`
`tiers[ending_unit][0..n]`	`tiers[ending_unit][0..n]`
`tiers[price][0..n]`	`tiers[price][0..n]`

Attached Addons

Product Catalog 1.0	Product Catalog 2.0
Create a plan `POST` `/api/v2/plans` A single call to this API can be used to attach all the required recurring and non-recurring addons to the plan.	Create an attached item `POST` `/v2/items/{item_id}/attached_items` Each call to this API attaches a single item (addon or charge) to the plan.
`id`	`{item_id}` (path parameter)
`attached_addons[id][0..n]`	`item_id`
`attached_addons[quantity][0..n]`	`quantity`
`attached_addons[billing_cycles][0..n]`	`billing_cycles`
`attached_addons[type][0..n]`	`type`
`event_based_addons[id][0..n]`	`item_id`
`event_based_addons[quantity][0..n]`	`quantity`
`event_based_addons[on_event][0..n]`	`charge_on_event`
`event_based_addons[charge_once][0..n]`	`charge_once`

Subscriptions

Create subscription for a customer

Product Catalog 1.0	Product Catalog 2.0
Create subscription for a customer `POST` `/api/v2/customers/{customer_id}/subscriptions`	Create a subscription for items `POST` `/v2/customers/{customer_id}/subscription_for_items`
`plan_id`	`subscription_items[item_price_id]`
`plan_quantity`	`subscription_items[quantity]`
`plan_unit_price`	`subscription_items[unit_price]`
`setup_fee`	`item`
`trial_end`	`subscription_items[trail_end]`
`billing_cycles`	`subscription_items[billing_cycles]`
`mandatory_addons_to_remove[0..n]`	`mandatory_items_to_remove[0..n]`
`addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`addons[billing_cycles][0..n]`	`subscription_items[billing_cycles][0..n]`
`addons[trial_end][0..n]`	`subscription_items[trail_end][0..n]`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`
`event_based_addons[on_event][0..n]`	`subscription_items[charge_on_event][0..n]`
`event_based_addons[charge_once][0..n]`	`subscription_items[charge_once][0..n]`
`event_based_addons[charge_on][0..n]`	`subscription_items[charge_on_option][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Update a subscription

Product Catalog 1.0	Product Catalog 2.0
Update a subscription	Update a subscription for items
`POST`* *`/api/v2/subscriptions/{id}`	`POST`* *`/api/v2/subscriptions/{subscription_id}/update_for_items`
`plan_id`	`subscription_items[item_price_id]`
`plan_quantity`	`subscription_items[quantity]`
`plan_unit_price`	`subscription_items[unit_price]`
`setup_fee`	`item`
`trial_end`	`subscription_items[trail_end]`
`billing_cycles`	`subscription_items[billing_cycles]`
`mandatory_addons_to_remove[0..n]`	`mandatory_items_to_remove[0..n]`
`addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`addons[billing_cycles][0..n]`	`subscription_items[billing_cycles][0..n]`
`addons[trial_end][0..n]`	`subscription_items[trail_end][0..n]`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`
`event_based_addons[on_event][0..n]`	`subscription_items[charge_on_event][0..n]`
`event_based_addons[charge_once][0..n]`	`subscription_items[charge_once][0..n]`
`event_based_addons[charge_on][0..n]`	`subscription_items[charge_on_option][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Cancel a subscription

Product Catalog 1.0	Product Catalog 2.0
Cancel Subscription	Cancel subscription for items
`POST`* *`/api/v2/subscriptions/{subscription_id}/cancel`	`POST`* *`/api/v2/subscriptions/{subscription_id}/cancel_for_items`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`

Invoices

Create an Invoice

Product Catalog 1.0	Product Catalog 2.0
Create an invoice	Create invoice for items and one-time charges
`POST`* *`api/v2/invoices`	`POST`* *`/api/v2/invoices/create_for_charge_items_and_charges`
`addons[id][0..n]`	`item_prices[item_price_id][0..n]`
`addons[quantity][0..n]`	`item_prices[quantity][0..n]`
`addons[unit_price][0..n]`	`item_prices[unit_price][0..n]`
`addons[date_from][0..n]`	`item_prices[date_from][0..n]`
`addons[date_to][0..n]`	`item_prices[date_to][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Create invoice for addon

Product Catalog 1.0	Product Catalog 2.0
Create Invoice for addon	Create invoice for charge-item
`POST`* *`api/v2/invoices/charge_addon`	`POST`* *`/api/v2/invoices/create_for_charge_item`
`addon_id`	`item_price[item_price_id]`
`addon_quantity`	`item_price[quantity]`
`addon_unit_price`	`item_price[unit_price]`
`date_from`	`item_price[date_from]`
`date_to`	`item_price[date_to]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Add addon item toa pending invoice

Product Catalog 1.0	Product Catalog 2.0
Add addon item to a pending invoice	Add a charge item to a pending invoice
`POST`* *`api/v2/invoices/{invoice_id}/add_addon_charge`	`POST`* * `/api/v2/invoices/{invoice_id}/add_charge_item`
`addon_id`	`item_price[item_price_id]`
`addon_quantity`	`item_price[quantity]`
`addon_unit_price`	`item_price[unit_price]`
`line_item[date_from]`	`item_price[date_from]`
`line_item[date_to]`	`item_price[date_to]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Coupons

Create a coupon

Product Catalog 1.0	Product Catalog 2.0
Create a coupon	Create a coupon for items
`POST`* *`/api/v2/coupons`	`POST`* *`/api/v2/coupons/create_for_items`
`plan_constraint`	`item_constraints[constraint][i]`
`plan_constraint`	`item_constraints[item_type][i]` = `plan`
`addon_constraint`	`item_constraints[constraint][i]`
`addon_constraint`	`item_constraints[item_type][i]` = `addon` or `charge`
`plan_ids[i]`	`item_constraints[item_price_ids][i]`
`addon_ids[i]`	`item_constraints[item_price_ids][i]`
N/A	`item_constraint_criteria[item_type][0..n]`
N/A	`item_constraint_criteria[item_family_ids][0..n]`
N/A	`item_constraint_criteria[currencies][0..n]`
N/A	`item_constraint_criteria[item_price_periods][0..n]`

Update a coupon

Product Catalog 1.0	Product Catalog 2.0
Update a coupon	Update a coupon
`POST`* *`/api/v2/coupons/{coupon_id}`	`POST`* * `/api/v2/coupons/{coupon_id}/update_for_items`
`plan_constraint`	`item_constraints[constraint][i]`
`plan_constraint`	`item_constraints[item_type][i]` = `plan`
`addon_constraint`	`item_constraints[constraint][i]`
`addon_constraint`	`item_constraints[item_type][i]` = `addon` or `charge`
`plan_ids[i]`	`item_constraints[item_price_ids][0..n]`
`addon_ids[i]`	`item_constraints[item_price_ids][0..n]`
N/A	`item_constraint_criteria[item_type][0..n]`
N/A	`item_constraint_criteria[item_family_ids][0..n]`
N/A	`item_constraint_criteria[currencies][0..n]`
N/A	`item_constraint_criteria[item_price_periods][0..n]`

Hosted Pages

Checkout a newsubscription

Product Catalog 1.0	Product Catalog 2.0
Checkout new subscription	Create a checkout for a new subscription
`POST`* *`/api/v2/hosted_pages/checkout_new`	`POST`* *`/api/v2/hosted_pages/checkout_new_for_items`
`subscription[plan_id]`	`subscription_items[item_price_id][0..n]`
`subscription[plan_quantity]`	`subscription_items[quantity][0..n]`
`subscription[plan_unit_price]`	`subscription_items[unit_price][0..n]`
`subscription[setup_fee]`	N/A
`subscription[trial_end]`	`subscription[trail_end]`
`subscription[billing_cycles]`	`billing_cycles`
`mandatory_addons_to_remove[0..n]`	`mandatory_items_to_remove[0..n]`
`addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`addons[billing_cycles][0..n]`	`subscription_items[billing_cycles][0..n]`
`addons[trial_end][0..n]`	`subscription_items[trail_end][0..n]`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`
`event_based_addons[on_event][0..n]`	`subscription_items[charge_on_event][0..n]`
`event_based_addons[charge_once][0..n]`	`subscription_items[charge_once][0..n]`
`event_based_addons[charge_on][0..n]`	`subscription_items[charge_on_option][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Checkout existing subscription

Product Catalog 1.0	Product Catalog 2.0
Checkout existing subscription	Create a checkout to update a subscription
`POST`* *`/api/v2/hosted_pages/checkout_existing`	`POST`* *`/api/v2/hosted_pages/checkout_existing_for_items`
`mandatory_addons_to_remove[0..n]`	`mandatory_items_to_remove[0..n]`
`billing_cycles`	`billing_cycles`
`coupon_ids[0..n]`	`coupon_ids[0..n]`
`subscription[id]`	`subscription[id]`
`subscription[plan_id]`	`subscription_items[item_price_id][0..n]`
`subscription[plan_quantity]`	`subscription_items[quantity][0..n]`
`subscription[plan_unit_price]`	`subscription_items[unit_price][0..n]`
`subscription[setup_fee]`	N/A
`subscription[start_date]`	`subscription[start_date]`
`subscription[trial_end]`	`subscription[trial_end]`
`subscription[invoice_notes]`	`subscription[invoice_notes]`
`subscription[contract_term_billing_cycle_on_renewal]`	`subscription[contract_term_billing_cycle_on_renewal]`
`addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`addons[billing_cycles][0..n]`	`subscription_items[billing_cycles][0..n]`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`
`event_based_addons[charge_on][0..n]`	`subscription_items[charge_on_option][0..n]`
`event_based_addons[on_event][0..n]`	`subscription_items[charge_on_event][0..n]`
`event_based_addons[charge_once][0..n]`	`subscription_items[charge_once][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Estimates

Estimate creating a subscription

Product Catalog 1.0	Product Catalog 2.0
Estimate creating a subscription	Estimate creating a subscription for items
`GET`* *`api/v2/customers/{customer_id}/create_subscription_estimate`	`POST`* *`/api/v2/customers/{customer_id}/create_subscription_for_items_estimate`
`subscription[plan_id]`	`subscription_items[item_price_id][0..n]`
`subscription[plan_quantity]`	`subscription_items[quantity][0..n]`
`subscription[plan_unit_price]`	`subscription_items[unit_price][0..n]`
`subscription[setup_fee]`	N/A
`subscription[trial_end]`	`subscription_items[trail_end][0..n]`
`billing_cycles`	`subscription_items[billing_cycles][0..n]`
`mandatory_addons_to_remove[0..n]`	`mandatory_items_to_remove[0..n]`
`addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`addons[billing_cycles][0..n]`	`subscription_items[billing_cycles][0..n]`
`addons[trial_end][0..n]`	`subscription_items[trail_end][0..n]`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`
`event_based_addons[on_event][0..n]`	`subscription_items[charge_on_event][0..n]`
`event_based_addons[charge_once][0..n]`	`subscription_items[charge_once][0..n]`
`event_based_addons[charge_on][0..n]`	`subscription_items[charge_on_option][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Estimate updating a subscription

Product Catalog 1.0	Product Catalog 2.0
Estimate updating a subscription	Estimate updating a subscription for items
`POST`* *`/api/v2/estimates/update_subscription`	`POST`* *`/api/v2/estimates/update_subscription_for_items`
`replace_addon_list`	`replace_items_list`
`subscription[plan_id]`	`subscription_items[item_price_id][0..n]`
`subscription[plan_quantity]`	`subscription_items[quantity][0..n]`
`subscription[plan_unit_price]`	`subscription_items[unit_price][0..n]`
`subscription[setup_fee]`	N/A
`subscription[trial_end]`	`subscription_items[trail_end]`
`billing_cycles`	`subscription_items[billing_cycles]`
`mandatory_addons_to_remove[0..n]`	`mandatory_items_to_remove[0..n]`
`addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`addons[billing_cycles][0..n]`	`subscription_items[billing_cycles][0..n]`
`addons[trial_end][0..n]`	`subscription_items[trail_end][0..n]`
`event_based_addons[id][0..n]`	`subscription_items[item_price_id][0..n]`
`event_based_addons[quantity][0..n]`	`subscription_items[quantity][0..n]`
`event_based_addons[unit_price][0..n]`	`subscription_items[unit_price][0..n]`
`event_based_addons[service_period_in_days][0..n]`	`subscription_items[service_period_days][0..n]`
`event_based_addons[on_event][0..n]`	`subscription_items[charge_on_event][0..n]`
`event_based_addons[charge_once][0..n]`	`subscription_items[charge_once][0..n]`
`event_based_addons[charge_on][0..n]`	`subscription_items[charge_on_option][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Create invoice estimate

Product Catalog 1.0	Product Catalog 2.0
Create invoice estimate	Estimate creating an invoice for items
`POST`* *`/api/v2/estimates/create_invoice`	`POST`* *`/api/v2/estimates/create_invoice_for_items`
`addons[id][0..n]`	`item_prices[item_price_id][0..n]`
`addons[quantity][0..n]`	`item_prices[quantity][0..n]`
`addons[unit_price][0..n]`	`item_prices[unit_price][0..n]`
`addons[date_from][0..n]`	`item_prices[date_from][0..n]`
`addons[date_to][0..n]`	`item_prices[date_to][0..n]`
N/A	`item_tiers[item_price_id][0..n]`
N/A	`item_tiers[starting_unit][0..n]`
N/A	`item_tiers[ending_unit][0..n]`
N/A	`item_tiers[price][0..n]`

Retrieving API Responses in Latest API Format

ImportantLearn more about legacy and latest product catalog's coexistence for upgraded sites.

Some Chargebee sites continue to use legacy API resources (Product Catalog 1.0) while gaining access to latest API (Product Catalog 2.0) capabilities. For such sites, specific GET API endpoints such as subscriptions, quotes, product catalog, coupons, invoices, and credit notes remain functional and return responses in the legacy API format by default.

To retrieve the latest and legacy response formats together, include the following header in your legacy GET API request:

chargebee-response-schema-type: compat

The possible values for chargebee-response-schema-type are:

plans_addons: The response format follows Product Catalog 1.0 using plans and addons.
items: The response format follows Product Catalog 2.0 using items.
compat (default): The response supports both Product Catalog 1.0 and 2.0 formats. Applicable only to sites that have been automatically upgraded to Product Catalog 2.0.

Note: If header values are not passed and your site is upgraded to the legacy and latest product catalog's coexistence, then by default this enum will be passed to the header.

Example of retrieving a subscription in latest API response format using specific legacy GET API request

Upgrading to Product Catalog 2.0

On this page

Resources

Endpoints

Plans

Addons

Coupons

Subscriptions

Invoices

Quotes

Gifts

Hosted Pages

Estimates

Parameters

Plans

Create a plan

Addons

Create an addon

Attached Addons

Subscriptions

Create subscription for a customer

Update a subscription

Cancel a subscription

Invoices

Create an Invoice

Create invoice for addon

Add addon item toa pending invoice

Coupons

Create a coupon

Update a coupon

Hosted Pages

Checkout a newsubscription

Checkout existing subscription

Estimates

Estimate creating a subscription

Estimate updating a subscription

Create invoice estimate

Retrieving API Responses in Latest API Format

Supported Legacy GET APIs