Quote-level sync status on zqu__Quote__c

Every Opportunity Product Sync attempt updates dedicated status and audit fields on the Quote (zqu__Quote__c) record. These fields are the first place to look when a quote fails to sync.

Quote-level status fields

The following fields track per-quote sync state and metadata:

Status values

Use the Opportunity Product Sync Status field to quickly understand where a quote sits in the sync lifecycle and what action is required.

Example SOQL queries for quote-level status

Use the following SOQL examples in Developer Console, Workbench, or the Salesforce API to find quotes by sync status.

Find all failed quotes

SELECT Id,
       Name,
       zqu__OppProdSyncStatus__c,
       zqu__OppProdSyncError__c,
       zqu__OppProdSyncLastDateTime__c,
       zqu__OppProdSyncVersion__c,
       zqu__Opportunity__c
FROM   zqu__Quote__c
WHERE  zqu__OppProdSyncStatus__c = 'Failed'
ORDER BY zqu__OppProdSyncLastDateTime__c DESC

Find sync status for a specific quote

SELECT Id,
       Name,
       zqu__OppProdSyncStatus__c,
       zqu__OppProdSyncError__c,
       zqu__OppProdSyncLastDateTime__c,
       zqu__OppProdSyncVersion__c
FROM   zqu__Quote__c
WHERE  Id = '<QUOTE_ID>'

Find quotes stuck in non-terminal states

Use this query to detect quotes that may have stalled in Queued or Sync Pending for more than approximately two hours.

SELECT Id,
       Name,
       zqu__OppProdSyncStatus__c,
       zqu__OppProdSyncLastDateTime__c
FROM   zqu__Quote__c
WHERE  zqu__OppProdSyncStatus__c IN ('Queued', 'Sync Pending')
AND    zqu__OppProdSyncLastDateTime__c < LAST_N_HOURS:2
ORDER BY zqu__OppProdSyncLastDateTime__c ASC

Central error log (zqu__Log__c)

Backend errors from all CPQ X operations, including Opportunity Product Sync, are written to the custom object zqu__Log__c via the platform event zqu__Log_Event__e. This is the shared CPQ X error log used across multiple components.

Log__c fields

zqu__Log__c records are created only when Error Logging is enabled and configured in Quote Configuration Settings > Advanced Quoting Configuration Settings. If it is disabled, Quote Studio does not generate any zqu__Log__c records for Opportunity Product Sync or other operations.

The following fields are relevant when troubleshooting Opportunity Product Sync failures:

Example SOQL queries for Opp Prod Sync errors

Find all Opportunity Product Sync errors

The Opportunity Product Sync components log errors using distinctive method names. Use those values in filters to find relevant entries.

SELECT Id,
       CreatedDate,
       zqu__Error_Message__c,
       zqu__Stack_Trace__c,
       zqu__Method_Name__c,
       zqu__Parent_Id__c,
       zqu__User_Id__c
FROM   zqu__Log__c
WHERE  zqu__Log_Level__c = 'Error'
AND   (zqu__Method_Name__c LIKE '%OppProdSync%'
       OR zqu__Method_Name__c LIKE '%ChargeSegmentOppProdSync%')
ORDER BY CreatedDate DESC

Find errors for a specific quote

Use this query to retrieve errors associated with a particular quote.

SELECT Id,
       CreatedDate,
       zqu__Error_Message__c,
       zqu__Stack_Trace__c,
       zqu__Method_Name__c
FROM   zqu__Log__c
WHERE  zqu__Quote__c = '<QUOTE_ID>'
AND    zqu__Log_Level__c = 'Error'
ORDER BY CreatedDate DESC

Known method names for Opp Prod Sync errors

The following values commonly appear in zqu__Method_Name__c for Opportunity Product Sync log entries. They help you identify the component that raised the error.

Sync audit trail object (zqu__OppProdSyncRecord__c)

The zqu__OppProdSyncRecord__c junction object stores the audit trail of successful Opportunity Product Sync operations. It is not an error log. Each record links a Quote to a synced Opportunity Product (OpportunityLineItem) and stores metadata about how charge segments were grouped.

Example SOQL queries for sync audit records

Find sync records for a quote

SELECT Id,
       Name,
       zqu__OpportunityProduct__c,
       zqu__Quote__c,
       zqu__ChargeSegmentGroupingKey__c,
       zqu__SegmentCount__c,
       zqu__SegmentEarliestStartDate__c,
       zqu__SegmentLatestEndDate__c,
       zqu__SyncDateTime__c,
       zqu__TotalDeltaQuantity__c
FROM   zqu__OppProdSyncRecord__c
WHERE  zqu__Quote__c = '<QUOTE_ID>'
ORDER BY zqu__SyncDateTime__c DESC

Find which quote synced a specific Opportunity Product

SELECT Id,
       zqu__Quote__c,
       zqu__SegmentCount__c,
       zqu__SyncDateTime__c,
       zqu__ChargeSegmentGroupingKeyFull__c
FROM   zqu__OppProdSyncRecord__c
WHERE  zqu__OpportunityProduct__c = '<OPPORTUNITY_LINE_ITEM_ID>'

Building Salesforce reports

You can build Salesforce reports and dashboards on top of the quote-level fields, logs, and sync audit records to monitor Opportunity Product Sync health.

• Report: Failed Opportunity Product Syncs

• Report: Opportunity Product Sync error log

• Report: Sync audit trail (successful syncs)

Dashboard idea: Opportunity Product Sync health

You can combine the reports mentioned in the above section into a dashboard to monitor overall health:

• KPI: Count of quotes with Failed status in the last 7 days.

• KPI: Count of quotes with Completed status in the last 7 days.

• Table: Top 10 most recent failures with error messages.

• Chart: Overall sync status distribution (for example, a pie chart of all status values).

Common scenarios and solutions

Log retention and cleanup

Error and information logs are cleaned up automatically according to configuration and log level.

• Error logs (Log_Level__c = 'Error'): Retained for the number of days set in Zuora_Config__c.Retention_Days__c.

• Info logs (Log_Level__c = 'Info'): Automatically purged after 2 days.

• Keep flag: Setting Keep__c = true on a zqu__Log__c record prevents that record from being deleted by the cleanup job.

• Cleanup job: The scheduled batch LogCleanupBatch purges old zqu__Log__c records based on the retention configuration.

Common fixes checklist

Use this checklist as a practical flow when you investigate an Opportunity Product Sync issue.

1. Check the Quote first

   On the Quote record, review zqu__OppProdSyncStatus__c and zqu__OppProdSyncError__c for the immediate error context.

2. Check the central log (zqu__Log__c)

   Query zqu__Log__c, filtered by the Quote ID in zqu__Parent_Id__c, to get full stack trace and method details.

3. Verify logging is enabled

   Confirm that Zuora_Config__c.Enable_Logging__c is set to true. If it is false, CPQ X does not write any zqu__Log__c records.

4. Check prerequisites

   • Feature enabled: Confirm Opportunity Product Sync is enabled (for example, zqu__OppProdSyncConfig__c.IsEnabled__c).

   • Charge segments exist: Ensure the quote has generated charge segments (run Order Preview first).

   • Primary quote: For multi-quote scenarios (MSQ), confirm the quote is the primary quote on the Opportunity.

   • Billing state: Check whether the quote has already been sent to Billing (Send to Zuora). Sync is blocked once the quote has been sent.

5. Check permissions.

   Verify that the running user has CREATE access on OpportunityLineItem and on all custom fields referenced in field mappings.

6. Retry the sync

   For transient or capacity-related failures, use the Sync Opportunity Products quick action again on the Quote record page after you have addressed the root cause.