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

Your Chargebee site now supports Product Catalog 2.0, which gives you access to new capabilities such as Subscription Ramps, Manual Discounts, Variant Pricing, and more. To explore the full set of features and benefits, refer to the Benefits of Product Catalog 2.0.

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.

Note:

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

If you're using the Chargebee API, you can continue to work with Product Catalog 1.0 APIs and webhook events without any disruption. This ensures business continuity and maintains the stability of your billing operations. You can choose to migrate to the Product Catalog 2.0 API at your own pace.

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:

Since GET API requests are common between the Product Catalog 1.0 and 2.0 subscription, quote, product catalog, invoice, and credit note APIs, Chargebee will return the Product Catalog 1.0 API response by default. To retrieve the response in the Product Catalog 2.0 format, include chargebee_response_schema_type value as items in your API request.

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?