home

Zuora CPQ

Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies
Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies

Welcome to Zuora Product Documentation

Explore our rich library of product information

Show Contents

thumbnailZuora CPQ

Opportunity Product sync

Configure Opportunity Product sync

Learn how to configure and enable Opportunity Product sync in Zuora CPQ.

Before you enable and configure Opportunity Product sync, ensure that:

  • The installed Zuora Quotes managed package version is 10.58 or above.

  • Orders is enabled in your Salesforce org so Order Preview can generate Charge Segments.

  • Charge Segment Metrics is enabled in Zuora Config > Quote Studio Settings > Admin Config.

    Note:

    The Opportunity Product Sync Execution toggle cannot be enabled unless Charge Segment Metrics is first enabled.

  • Opportunity Product sync feature is enabled by Zuora Support..

  • Error Logging is enabled and configured in Quote Configuration Settings > Advanced Quoting Configuration Settingsto gain better visibility into errors.

  • Only one primary quote per Opportunity is synced.

    (Optional but recommended) Enforce a single primary quote per opportunity so that, regardless of how many quotes are created, only the quote most recently marked as Primary remains the active primary quote. Only primary quotes can be synced.

    Configure per quote type as follows:

    • For Single Subscription Quoting (SSQ) you can enable it from Zuora Config > Quote Configuration Settings > Enforce Single Primary Quote.

    • For Multi Subscription Quoting (MSQ) you can enable it from Zuora Config > Quote Studio Settings > Admin Config > Enforce single MSQ Primary Quote per Opportunity.

  • Users are assigned the Zuora Quotes End User permission set and have create/edit access on Opportunity Products, along with appropriate field-level security access to the Quote sync status field. See Permissions and security updates.

  • The Standard Pricebook must be enabled in Salesforce. If no matching Pricebook Entry exists, a shell entry is created to enable Opportunity Product creation.

  • Custom fields should be created on Opportunity Products to capture the desired metrics. See Custom fields creation on Opportunity Product.

  • Sync status fields and related lists are added to the appropriate page layouts. See

  1. Log in as a Salesforce user with the required permissions to configure Opportunity Product sync.
  2. Enable Opportunity Product sync.
    1. Navigate to Zuora Config > Quote Studio Settings > Admin Config.
    2. In the left navigation, click Opportunity Product Sync.
      Note:

      The option appears automatically once the feature is enabled in your Salesforce org by Zuora support.

    3. Use the Enable Opportunity Product Sync Execution toggle at the top of the settings page to turn the feature on or off.
      Note:

      • When enabled, quotes can be synced manually or automatically according to your configuration.

      • When disabled, all sync behavior is paused, but your configuration is preserved.

  3. Configure sync settings to control which types of charges are included in the sync. See Sync settings.
    Note:

    Turn off Zero-Dollar Charges if you want cleaner Opportunity Products data without $0 line items.

  4. Configure auto-sync triggers. You can run sync automatically based on lifecycle events or manually from a quote.You can configure sync to run automatically when:

    • Quote Approval Status becomes Approved.

    • You click Submit and not on Save.

    • The quote is submitted to Zuora (Send to Billing).

    All auto-sync triggers:

    • Validate that Charge Segments exist before syncing.

    • If Charge Segments are missing, the status is set to Waiting for Charge Segments.

    • Duplicate sync requests are prevented through internal deduplication.

  5. Configure the batch size, minimum available queueable slots, and minimum CPU time (in milliseconds) required before enqueueing. The configured batch size (default: 5 quotes) controls how many quotes are processed per run.

    For batch size behavior, see Batch size in Opportunity Product sync.

    Note:

    • Use a smaller batch size, for example, 2–3 for complex quotes with many charges or ramp intervals.

    • The batch processor is designed to handle 1,000+ Charge Segments per quote while staying within Salesforce governor limits.

  6. Configure grouping keys. See Grouping keys configuration.

    Grouping keys determine how Charge Segments are combined into Opportunity Products.

  7. Configure line creation mode. See Line creation mode configuration.

    Line creation modes control how Opportunity Products are split within each grouping-key group.

  8. Configure field mappings. See Configure field mappings.

    Field mappings define which Zuora CPQ values populate which Opportunity Products fields. Four required mappings are auto-created and cannot be deleted, but the sources may be edited:

    • OpportunityId (auto-set from Quote)

    • PricebookEntryId (auto-set from Product)

    • Quantity (sourced from Charge Segment zqu__Quantity__c)

    • TotalPrice (sourced from Charge Segment zqu__NetTCB__c)

    To add a mapping for a custom metric:

    1. Ensure the custom field exists on the Opportunity Product object in Salesforce if it does not already exist.
    2. In the Field Mapping section, click Add optional mapping.
    3. In the New field mapping window perform the following steps:

      1. Provide a mapping name.

      2. Select the destination field. For example, Delta Quantity.

      3. Select the source object and field. For example, Charge Segment – Delta Quantity.

      4. Save the mapping. On the next sync, Opportunity Products are populated with the appropriate delta quantity from each charge or interval.

    Note:

    • Mappings can be activated/deactivated without deleting.

    • Available source objects include:

      • Charge Segment (primary)

      • Quote Rate Plan Charge

      • Quote Rate Plan

      • Product Rate Plan

      • Product2

  9. Click Save.
  10. Add the Sync Opportunity Products button. See Add Sync Opportunity Products button.
    Note:

    This step is required for manual sync access. The Sync Opportunity Products button is not automatically added on Quote pages.

  11. Add the sync status fields and related lists to page layouts. See

Last updated: May 4, 2026