Product Catalog Upgrade

Overview

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

As part of the Product Catalog Upgrade, your Chargebee site has been upgraded to support the Latest Product Catalog, while continuing to support Legacy Product Catalog APIs through coexistence mode. This setup ensures that your existing workflows remain stable, while giving you the flexibility to adopt new features in Latest Product Catalog 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 Latest Product Catalog.

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

What Has Changed in the User Interface?

Product Catalog

Latest Product Catalog 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 Legacy Product Catalog plans containing setup fees, a non-recurring charge is auto-created in Latest Product Catalog 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: Latest Product Catalog 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.

What Has Changed in Chargebee API?

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

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

Access New Features with Latest Product Catalog 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 Latest and Legacy Product Catalog 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. 

What Has Changed in Events?

Webhook events are backward compatible. All webhook events will be generated in both the Legacy and Latest Product Catalog 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 Legacy Product Catalog version.

Considerations While Using Latest Product Catalog

• Plan and addon filter segments cannot be saved within the Product Catalog index page.
• Due to changes in the product catalog structure, the Latest Product Catalog 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.
• Legacy Product Catalog-related plan and addon events cannot be viewed in the Latest Product Catalog user interface. However, the events will be sent to the configured webhook URL.

Product Catalog Upgrade FAQs

About the Upgrade

Why is Chargebee upgrading my account?

Over the past few years, Chargebee has built significant new capabilities around pricing, packaging, and monetization. Until now, accessing those capabilities required a complex, manual effort on your part. The product catalog upgrade removes that barrier. It brings your account onto a modern foundation so you can access new features when you choose to, without disrupting anything you rely on today.

What exactly is changing?

Your product catalog is being upgraded to a newer version behind the scenes. You will see an updated interface in the product catalog section, including the introduction of product families and price points. Your existing plans, add-ons, pricing, and subscription behavior all remain the same. The upgrade expands what is possible without modifying what is already in place.

Is this a migration?

No. A migration would require you to rebuild or reconfigure your setup. The product catalog upgrade preserves your existing configuration, APIs, and integrations. Everything you use today continues to work.

Impact on Your Business

Will I lose any functionality?

No. All existing functionality is preserved. Your APIs and integrations continue to operate exactly as they do today. You only need to invest effort if and when you choose to adopt new capabilities.

Will my billing data or subscriptions change?

No. Your existing subscriptions, billing data, customers, and revenue flows are not affected. The upgrade changes the catalog infrastructure behind the scenes without touching your active billing.

Will my customers notice anything different?

No. The upgrade does not affect your customer-facing experience. Your checkout flows, invoices, and subscription behavior remain unchanged.

Will there be any changes to the plan or price I pay Chargebee?

No. You will remain on the same Chargebee plan after the upgrade and continue paying the same subscription amount.

Technical Details

Will there be any downtime?

No. There is no downtime during the upgrade. You can continue using Chargebee as usual. The only thing we ask is that you avoid creating new product catalog items during the upgrade window, which typically lasts one to two hours.

How long does the upgrade take?

The upgrade is completed within a scheduled maintenance window, typically one to two hours. Most of the process is handled automatically on our end.

Do I need to make any API changes?

For your existing setup, no. Your current APIs continue to work as they do today.

If you later choose to adopt features that are only available in the newer version (for example, manual discounts or contract terms in subscription APIs), you would use the updated API for those specific calls. Everything else can stay on your current API version. You can adopt at your own pace, and your team decides what to move and when.

Will my current APIs be deprecated?

There are no plans to deprecate your current APIs. Backward compatibility was built into the upgrade specifically so you can continue using your existing API calls while also having access to newer capabilities when you are ready.

Do I need to update my SDKs?

No. Your SDK connections will continue to work after the upgrade without any changes.

How are webhooks and events handled after the upgrade?

After the upgrade, webhook events are sent in the compatible format by default. A configuration option is also available that lets you choose which version of events to listen to. Your Chargebee team can walk you through the details based on your setup.

Integrations

Are my existing integrations supported?

Yes. Major integrations, including NetSuite, QuickBooks, Slack, Intercom, and HubSpot, are fully compatible. Some integrations, such as Salesforce, Zapier, and RevRec, have partial support at launch and are being expanded. Your Chargebee team can confirm the status of any specific integration you rely on.

What happens if I use Hosted Pages V2?

If your site is currently on Hosted Pages V2, we will upgrade you to Hosted pages V3 before the product catalog upgrade. Your Chargebee team or Chargebee Support can walk you through any changes to the checkout script and page appearance ahead of time so there are no surprises.

Catalog and Setup

Do I need to re-map my product catalog?

If you are happy with your existing catalog setup, no mapping is needed. Everything carries over as-is.

If you want to take the opportunity to consolidate or restructure your catalog (for example, merging duplicate plans or simplifying addon structures), your Chargebee team will provide a mapping sheet for your review and confirmation before any changes are made.

What if I have duplicate plan or addon IDs?

Duplicate IDs need to be resolved before the upgrade can proceed. Your Chargebee team will flag any duplicates during the eligibility review and work with you to clean them up before scheduling the upgrade.

Is my site eligible for the upgrade?

Eligibility depends on a few technical factors, including whether your site has duplicate IDs, unsupported characters in plan or addon names, or incompatible integrations. Your Chargebee team will run an eligibility check and let you know if anything needs to be addressed before moving forward.

Testing and Rollback

Can I test the upgrade before it goes live?

Yes. Chargebee can create a dedicated proof-of-concept site that mirrors your live product catalog data. You can explore the upgraded experience in a safe environment without affecting your live or test sites.

Can I roll back to my previous setup if needed?

Yes. Rollback is supported. If you experience any issues after the upgrade, your Chargebee team can restore your previous configuration.

Support

What support does Chargebee provide during the upgrade?

You will have access to updated API documentation, catalog mapping assistance if needed, a proof-of-concept test site, and rollback support. If you have a dedicated Account Manager or Technical Success Manager, they are available to walk you through the updated interface and answer questions. If you don't have a dedicated contact, Chargebee Support is available to help you through every step of the process.

Who should I contact if I have questions?

Reach out to your Account Manager or Technical Success Manager. If you don't have a dedicated contact, you can reach Chargebee Support. They can answer questions about timing, eligibility, integration compatibility, and anything else related to the upgrade.