Other considerations for the upgrade

Before you upgrade, review the following considerations related to the data model, UI behavior, plugins, customizations, and reporting.

Data model

Quote Studio UI intends to use the same data structure as Legacy CPQ UI, provided that Orders is enabled in your legacy CPQ UI. You can open a quote created using the Legacy CPQ UI with the new functionalities of Quote Studio UI.

Zuora added new fields and behaviors, particularly around preview metrics, which introduce notable changes in reporting. Some data might appear to be missing when you switch from one flow to another.

In Quotes version 10.36, Zuora added an object type called Charge Segments, significantly impacting customers who originally built reports using Quote Rate Plan Charge and Quote Charge Summaries.

See Charge Segment.

Behavior differences between Legacy CPQ UI to Quote Studio UI

The Quote Studio UI is a single-page application. Quote data remains in the browser until you explicitly choose to save the quote. In contrast, Legacy CPQ UI saves the quote on each page, the Rules Engine does not trigger until all products are added to the quote, and previewing occurs only on the Quote Detail page. This change in the UI has the following significant impacts:

• Timing of when quote data is saved to the database.

• Timing of rules engine execution.

• Timing of quote previews.

• User configurations are not visible in the database when rules are triggered.

• Custom updates made to the database are not reflected in the live configuration quote.

• In-memory Quote Studio data can be manipulated through the Extensibility Framework. See Extensibility Framework.

Guided Product Selector alternatives

The Guided Product Selector has the following impacts in the Quote Studio UI:

• You can continue to use the legacy Guided Product Selector flows with Quote Studio. See Combine guided selling with Quote Studio. Instead of the Guided Product Selector, you can use the Quick Filter and Product Filter feature in Quote Studio UI, which offers a more intuitive product filtering system, helping sales users choose the right products easily. See Configure product filters and quick filters.

• The Quote Studio UI does not support adding custom components to the Guided Selling steps. As an alternative to adding custom field sets, Quote Studio UI provides the option to use the existing Additional Fields field sets and relabel them to add new sections in the UI. See Customize labels and Customize field sets.

• Legacy layout configuration is not available in Quote Studio UI. Alternatively, in Quote Studio UI, you can configure the layout using field sets similar to Legacy CPQ UI. See Customize field sets for CPQ X.

• Quote Studio UI does not support inserting custom components or custom field sets within the Quote Studio UI, which was supported in the Legacy CPQ UI through the layout configuration settings. As an alternative to adding custom field sets, Quote Studio UI provides the option to use the existing Additional Fields field sets and relabel them to add new sections in the UI. See Customize labels and Customize field sets.

• Customizing sections, adding, or hiding buttons on the Quote Studio page is not yet supported. Relabelling button names or sections in the Quote Studio UI is possible through the Salesforce Translation Workbench override feature. See Localize and customize labels and messages.

• The JavaScript plugin is not supported in Quote Studio UI. However, the Custom Action Plugin is available in Quote Studio and can perform every function of the JavaScript plugin and more. Additionally, you can use the Extensibility Framework to write JavaScript to manipulate in-memory Quote Studio data.

• The legacy QuickFilter Component and QuickList Component are not supported in Quote Studio UI. Alternatively, you can use the Quick Filter option in Quote Studio UI. See Configure product filters and quick filters.

Legacy plugins and custom components

The legacy CPQ extensibility tools that existed, such as the Zuora CPQ Component Library, Zuora CPQ Global Classes, Product Selector JavaScript Plugin, and Zuora CPQ Global Components, do not directly apply when adopting Quote Studio UI.

The following legacy mechanisms are not supported in Quote Studio UI:

• Custom components inserted into Guided Selling steps.

• Custom components or custom field sets inserted within the legacy layout configuration model in the quote flow.

• Product Selector JavaScript Plugin.

• Legacy QuickFilter Component and QuickList Component.

Quote Studio UI provides the following alternatives:

• Use the existing Additional Fields field sets and relabel them to add sections in the Quote Studio UI.

• Use the Custom Action Plugin when you need product or quote manipulation logic in Quote Studio.

• Use the Extensibility Framework to run JavaScript against in-memory Quote Studio data.

• Use Quick Filter in Quote Studio instead of the legacy QuickFilter and QuickList components.

• Use supported Quote Studio plugins such as Billing Account Plugin, Default Values Plugin, Entity Plugin, and Lookup Filter Plugin when they satisfy the customization need.

Components on the Quote Details page can remain unchanged and continue to function as they did in the Legacy CPQ UI. However, review components embedded within the legacy CPQ UI steps carefully before you move to the Quote Studio UI.

Rules Engine and Custom Action Plugin considerations

The Legacy CPQ Rules Engine is available in Quote Studio UI, but significant changes in data residency and execution timing require you to review existing configurations.

• You must enable the Rules Engine in Quote Studio UI. See Enable Rules Engine.

• Custom Action Plugins - If you already implemented Custom Action Plugins in the Legacy CPQ UI, update them to work with the Quote Studio API set and execution model.

  • API usage differences - The most important change is that Custom Action Plugins now receive the QPlan data model instead of the zChargeGroup object model. Existing implementations that depend on zChargeGroup behavior might no longer work as expected and must be updated accordingly. See CPQ X API.

  • Data Residency and Expectation Changes - Review plugin logic that queried Quote or related records from the database during Rules Engine execution. In Quote Studio UI, reading from the database during quote editing can return outdated information, because the live quote remains in memory until the user saves or submits the quote. Custom Action Plugins must rely on the DataObject attribute to access in-flight quote data.

• Rules Engine Plugin - Another backward incompatibility of Quote Studio UI is the removal of the Rules Engine Plugin support, which was previously used to run custom logic before Rules Engine evaluation. Zuora recommends using the beforeRulesExecution hooks in the Extensibility Framework as an alternative for implementing custom logic. See Headless component - hooks.

• Timing - Quote Studio UI features Quote Studio as a streamlined Quoting experience, emphasizing the importance of rules firing at various stages of the quoting process. Quote Studio UI includes the concept of "Trigger Events," which categorizes rules based on their execution timing. Zuora supports the following out-of-the-box trigger events when:

  • The Quote Studio page loads

  • You make changes to the quote

  • You save or exit the Quote Studio page

The ability to define when the rules need to trigger improves product performance, because rules are not executed all the time. Larger quotes and a greater number of rules can impact the performance if rules are always firing. Using the trigger events improves the product performance.

• Time awareness - Quote Studio UI also makes future-dated quoting more intuitive, which exposes a limitation of the Rules Engine, because it cannot evaluate rules with a date context. To address this, you can review the active interval from which the user is triggering rules and use the Extensibility Framework to execute the Rules Engine on demand and filter the rules that need to run.

  • Quotes version 10.36.1

    • Review the active interval from which the user is triggering rules.

    • Execute the Rules Engine on demand and filter the rules to be executed by using the Extensibility Framework implementation. See Headless component - hooks.

  • Quotes version 10.37 - Add, update, or remove a rate plan on a specific date instead of the Quote Start Date using the Custom Action Plugin. See Custom Action.

• MSQ support - Currently, the Rules Engine cannot recognize Quotes under the same parent Quote. Zuora is actively working on a solution to address this issue.

Extensibility Framework

Because CPQ X no longer supports Quote Wizard or step pages for executing Apex Triggers or custom code, you might require a programmatic way to interact with the live Quote in the browser.

To address this, Zuora introduced the Extensibility Framework, which enables the real-time injection of custom logic as you edit quotes using the following mechanisms:

• Create a Custom UI component that slides out within the Quote Studio page to interact with the Quote Studio data based on user input.

• Create a Headless component to execute your custom logic that manipulates in-page data in Quote Studio.

The Extensibility Framework offers the following two key capabilities:

• Access to in-flight quote data in the browser.

• Detection of user actions on the Quote Studio page.

By utilizing hooks (logic that executes when specific events occur) and events (notifications that prompt actions on the page), you can achieve a wide range of custom functionalities, including replicating a rules engine directly on the page, without being limited by Apex constraints. See Extensibility Framework.

Considerations for other customizations

Review the following customization areas to identify changes required before you move to the Quote Studio UI.

Triggers

Triggers that relied on quote-level data being saved at each step in the Legacy CPQ UI now require reconsideration in the Quote Studio UI. Because the Quote Studio UI is a single-page application, quote data remains in the browser until you click Save or Submit. As a result, trigger logic that depended on intermediate database saves might no longer run at the expected time or with the expected data.

If your implementation uses Salesforce triggers to update or validate quote data while the sales user is still editing the quote, redesign that logic to work with in-memory Quote Studio data instead of relying on the database state. For custom logic that must run before the quote is saved, use the Extensibility Framework so that the logic can interact with the live quote in the browser.

If your legacy implementation used trigger-driven logic before Rules Engine evaluation, note that Quote Studio UI no longer supports the legacy Rules Engine Plugin. Use the beforeRulesExecution hooks in the Extensibility Framework as the recommended alternative for running custom logic before rules are evaluated.

Custom Components

The legacy CPQ extensibility tools that existed, such as the Zuora CPQ Component Library, Zuora CPQ Global Classes, Product Selector JavaScript Plugin, and Zuora CPQ Global Components, no longer directly apply when adopting Quote Studio.

If you use Custom Components in your legacy CPQ implementation, analyze them by asking the following questions:

• What business case does the component or mechanism of the Extensibility Framework mechanism solve?

• Is the business case natively resolved within Quote Studio through configuration or user experience? If not, how can the business case be optimized by using the Quote Studio Extensibility Framework?

Based on your analysis, assess whether the out-of-the-box experience in Quote Studio UI or new features in Billing supported by Quote Studio resolve some of these business cases natively without requiring customization.

If you identify customizations that your organization still requires and that are not natively satisfied by the Quote Studio UI or Billing features supported in Quote Studio, use the following tools to achieve the customization:

• Rules Engine

• Rules Engine with custom action plugin

• Extensibility Framework

• Quote Studio supported plugins

  • Billing Account Plugin

  • Default Values Plugin

  • Entity Plugin

  • Lookup Filter Plugin

Components on the Quote Details page can remain unchanged and continue function as they did in the Legacy CPQ UI. However, review components embedded within the Legacy CPQ UI steps carefully.

Custom Visualforce pages and Quote Wizard flows

Quote Studio UI does not use the legacy Quote Wizard or step-page model for executing Apex triggers or custom code. If your legacy implementation depends on custom Visualforce pages or Quote Wizard flows inside the quoting journey, those customizations do not transition directly to Quote Studio UI and must be redesigned.

Use the Extensibility Framework based on your business need:

• Use a Custom UI component when sales users must provide input or interact with quote data while editing the quote. A Custom UI component slides out within the Quote Studio page and work with Quote Studio data in real time.

• Use a Headless component when you need background logic that validates, enriches, or updates quote data without adding a visible user interface.

• Use hooks and events when the customization must respond to user actions or to specific stages in the quote lifecycle.

Before you redesign a custom Visualforce page or Quote Wizard step, first confirm whether the business need is already covered by standard Quote Studio configuration or by Billing functionality supported in Quote Studio. Reimplement the customization only when the out-of-the-box experience does not satisfy the business need.

API (Global Methods) differences

The Quote Studio page introduces a new set of Global Method APIs: QPlan, QCharge, QTier, and QAmendment. Unlike the legacy zChargeGroup and zCharge objects, these new APIs are designed for improved performance and include built-in remove and revert methods. Combined with the utility classes QPlanBuilder and QPlanWriter, they replace traditional zQuoteUtil methods and provide a more modular and scalable approach to quote manipulation. For sample code, see Sample code using zChargeGroup.

Most of the functionalities offered by the zChargeGroup and zCharge classes are available through the CPQ X APIs. However, the absence of explicit method declarations might make it less intuitive for developers unfamiliar with the object data model. Use the following references to learn about how to access the different methods and properties using QPlan and QCharge.

• zChargeGroup to QPlan

• zCharge to QCharge

When you review legacy code, note that some legacy behaviors do not map directly. For example, some Visualforce-related methods are no longer supported in LWC Quote Studio, some legacy product selector interactions are not supported through QPlan APIs, and some legacy bundle or option behaviors are no longer represented in the same way in QPlan.

Custom Fields

Certain legacy custom fields that were originally mapped as "text" in Zuora but of different data types in Salesforce can trigger errors in Orders API calls. Zuora recommends migrating and remapping the Zuora custom fields to their correct data types.

A backward-compatible solution is available if you have long-standing implementations that are based on these custom fields and cannot be migrated. You can add fields to the Retain Custom Field Data Type object field sets and when the Legacy Support: Send SF Custom Fields to Zuora as String setting is activated, any custom fields included in this field set are excluded from conversion to strings when the quote is sent to Zuora. See Quote Configuration Settings.

Usage Tracking

With the upgrade to CPQ version 10 or later, there is a remote site setting to enable callouts to Amplitude. This setting allows Zuora to track user telemetry and usage analytics, primarily for quote creation data and errors. Data collection is limited to Quote Studio UI usage and does not affect Legacy CPQ UI.

Lightning Web Security (LWS) enablement

Lightning Web Security (LWS) enhances communication between components and modules across different namespaces for the Lightning Web Component Framework. Enabling LWS significantly boosts Quote Studio UI performance, particularly when enabling custom components.

One key consideration is the compatibility of other integrations, because not all AppExchange packages support LWS. You might encounter issues when you enable LWS for Quote Studio UI. Zuora strongly recommends testing LWS in a fully replicated sandbox environment to prevent disruptions when implementing Quote Studio UI.

Internationalization considerations

Quote Studio UI does not currently offer out-of-the-box support for internationalization. However, you can configure specific language support by using the Translation Workbench in Salesforce. See Localize and customize labels and messages. If you encounter any text that is unavailable for translation in the workbench, create a support ticket.

You can use the override feature of the Translation Workbench to override the custom label in Quote Studio. See Localize and customize labels and messages.

ICU locale concerns

All Quote Studio UI components are built with API versions above 58.0, thus compatible with ICU locale requirements. With Quotes version 10.20, Zuora CPQ for Salesforce is fully compatible with the International Components for Unicode (ICU) locale enforcement by Salesforce. See International Components for Unicode (ICU) Locale Formats.

Zuora is actively working on upgrading Legacy CPQ UI components to API versions later than 45.0. Given the incompatible API version warning, the package should function without error. See the community post.

Reporting and metrics dependencies

Before you move users to Quote Studio UI, review the following reporting and metrics dependencies:

• Reports that reference Quote Rate Plan Charge or Quote Charge Summary records and assume the pre-Quote Studio structure.

• Dashboards or calculations that depend on preview metrics without accounting for the newer Quote Studio preview behavior.

• Legacy implementations where Orders or Store Existing Products was not enabled before Quote Studio adoption.

If your organization has custom reporting, exports, integrations, or downstream processes built on legacy quote metrics, validate those assets in a sandbox after you enable Orders and Store Existing Products and before you move users to Quote Studio UI in production.