Docs

Log in to read the version of docs relevant to your site, or use the dropdown versions

Product Catalog Coexistence: A Guide for Upgraded Sites

Overview

This document helps you understand what changes in the user interface and APIs occur when Product Catalog 1.0 and 2.0 coexist on your site.

Your Chargebee site now supports Product Catalog 2.0, while also continuing to support Product Catalog 1.0 APIs through coexistence mode. This setup ensures that your existing workflows remain stable, while giving you the flexibility to adopt new features in Product Catalog 2.0 at your own pace.

With coexistence enabled, you gain access to capabilities such as Subscription Ramps, Manual Discounts, Variant Pricing, and more.
To learn about the complete set of features, see Benefits of Product Catalog 2.0.

Note:

All subscription actions, such as create, update, cancel, and related invoice operations performed through the Chargebee user interface are processed in the Product Catalog 2.0 format. As a result, any events triggered in the UI and sent to webhook listeners also follow this format.

If you are using the Chargebee API, you can continue to work with Product Catalog 1.0 APIs and webhook events without disruption.
This ensures continuity for your current billing operations. You can choose to migrate to the Product Catalog 2.0 API whenever you are ready.

What Has Changed in the User Interface?

Product Catalog

Product Catalog 2.0 allows you to group plans and addons across currencies and billing frequencies, simplifying the process of adding and updating pricing. Additionally, it introduces product families, which group multiple plans and addons belonging to a single business vertical.

A default product family containing all existing plans and addons is auto-created in your Chargebee site. Each product in your catalog is mapped one-to-one between the older and latest product catalog versions.

Price Point

To access a plan, click Product Catalog > Plans > Search the Plan > Select the relevant Price Point that applies.

Setup Fees

For all product catalog 1.0 plans containing setup fees, a non-recurring charge is auto-created in product catalog 2.0 under Product Catalog > Charges with the naming convention 'Setup Fee'. This charge is attached to the relevant plan when the subscription is activated, as shown below. Note: Product Catalog 2.0 does not support adding setup fees during plan creation.

Coupons

Use the latest coupon features, such as criteria-based coupons and restrictions that apply to new or existing customers.

Subscription and Quote

The default product family is auto-created and pre-selected. To create a new subscription, click the Product Family drop-down and select the product family of the plan for which you are creating the subscription.

Note:

Only plans and addons that belong to the same product family can be added to a subscription. The same rule applies when updating a subscription.

What Has Changed in Chargebee API?

For sites where Product Catalog 1.0 and 2.0 coexist, create, update, and manage operations will continue to function. For each plan and addon created via the Product Catalog 1.0 API, Chargebee will automatically call the equivalent Create an item and Create an item price API to create the same product in the Product Catalog 2.0 API structure.

Note:

Plans and addons cannot be created with duplicate IDs when your site coexists in Product Catalog 1.0 and 2.0.

All related operations, such as managing subscriptions, estimates, invoices, and credit notes, will continue to use the Product Catalog 1.0 API set and return responses in the same format to ensure business continuity.

Access New Features with Product Catalog 2.0 APIs (Optional)

  • Latest features such as Subscription Ramps, Price Variants, Manual Discounts, etc., can be accessed on the Chargebee site via UI and API. 

  • Both product catalog 2.0 and 1.0 APIs will be accessible on the same site. 

  • If you would like to adopt a new feature, only the API endpoints impacted by the new feature need to be updated to the latest version. You can do this at your own pace. 

Note:

For sites where Product Catalog 1.0 and 2.0 coexist, GET API requests for subscriptions, quotes, invoices, and credit notes return responses in a compatibility format.

To explicitly request this format, include the following header in your API request: If the header is not passed, and your site supports coexistence, the value compat is applied by default.

For details, see chargebee_response_schema_type and retrieving API responses in latest API format(Product Catalog 2.0).

What Has Changed in Events?

Webhook events are backward compatible. All webhook events will be generated in both the product catalog 1.0 and 2.0 formats on the same site, as shown below. A new field, Response Schema Type, has been introduced in the UI to switch between both versions.

At the webhook configuration level, you can also decide which version of the event should be sent to your webhook listener. By default, all events will be sent in the product catalog 1.0 version.

Considerations While Using Product Catalog 2.0

  • Plan and addon filter segments cannot be saved within the Product Catalog index page.
  • Due to changes in the product catalog structure, the product catalog 2.0 user interface does not support cloning plans or addons.
  • Plans and addons cannot be exported directly from the index page. To export, go to Settings > Import and Export Data > Manual Export > Product Catalog > Click Export File.
  • Product Catalog 1.0-related plan and addon events cannot be viewed in the Product Catalog 2.0 user interface. However, the events will be sent to the configured webhook URL.

See also

Was this article helpful?