Cpq Performance Optimization

CPQ Performance Optimization

This skill activates when a Salesforce CPQ implementation is experiencing slow or failing quote calculations, QLEx timeouts, or governor limit errors at scale. It covers the primary platform levers — Large Quote Mode, QCP field declaration discipline, and static resource architecture for large plugins — and explains the exact trade-offs each choice forces.

Before Starting

Gather this context before working on anything in this domain:

• Line count: What is the typical and maximum quote line count for deals in this org? The synchronous CPQ calculation engine starts to produce governor pressure around 200–300 lines. Large Quote Mode is the primary lever past that threshold.
• QCP field declarations: Does the org use a Quote Calculator Plugin? If yes, pull the current fieldsToCalculate and lineFieldsToCalculate arrays. Undeclared fields cause silent null reads; overdeclared fields inflate the JSON payload sent to the calculation engine.
• SBQQ__Code__c size: Is the QCP code currently stored inline in SBQQ__Code__c? That field is hard-capped at 131,072 characters. Large plugins must use a Static Resource loaded via eval().
• Large Quote Mode status: Check CPQ Package Settings > Large Quote Mode and the threshold value (default 100 lines). Confirm whether SBQQ__LargeQuote__c on the Account record is also in use — the mode can be toggled at the account level independently of the package setting.
• Calculate Quote API usage: If the org uses the SBQQ.ServiceRouter calculate API in Apex batch jobs, understand that it runs at async speed — it does not bypass governor limits and is not a substitute for Large Quote Mode on large quotes.

Core Concepts

Large Quote Mode

Large Quote Mode shifts quote calculation from a synchronous in-browser model to an asynchronous server-side model. When enabled and the quote line count exceeds the configured threshold, the CPQ engine queues a server-side calculation job and returns control to the user immediately. The QLE displays a "calculating" status indicator; reps cannot save or submit the quote until calculation completes.

This is a UX-breaking change. Reps accustomed to immediate recalculation will see a delay and a status indicator they have not seen before. Enablement without user communication causes support tickets. The threshold must be tuned: too low and reps are interrupted on medium quotes; too high and large quotes still hit governor limits.

Large Quote Mode is controlled at two levels: (1) the CPQ Package Settings field "Large Quote Mode" with a line count threshold, and (2) the SBQQ__LargeQuote__c checkbox on the Account record, which forces async mode for all quotes on that account regardless of line count. Both controls must be considered.

QCP Field Declaration

A Quote Calculator Plugin must declare every field it intends to read or write in two arrays: fieldsToCalculate (quote header fields) and lineFieldsToCalculate (quote line fields). CPQ uses these declarations to build the JSON payload sent to the plugin; fields not declared are excluded from the payload entirely.

Two failure modes exist:

• Underdeclaring: The plugin reads a field that is not declared. The field value is null in the payload. The plugin operates on null silently — no error is thrown, pricing logic produces wrong results, and the bug is hard to diagnose.
• Overdeclaring: Fields are declared "just in case." Each additional field increases JSON payload size, calculation API call size, and round-trip time. On 200+ line quotes the overhead compounds.

The correct discipline is to declare exactly the fields the plugin reads or writes — no more, no less. This requires auditing the plugin code against the declaration arrays.

SBQQ__Code__c Size Limit and Static Resource Architecture

The SBQQ__Code__c field on the SBQQ__CustomScript__c object stores QCP JavaScript inline. The field is a Long Text Area capped at 131,072 characters. Modern QCPs that include helper functions, pricing tables, or complex bundle logic routinely exceed this limit.

The correct architecture for large plugins is to store the JavaScript in a Static Resource and load it at runtime using eval(). The inline SBQQ__Code__c field holds only the bootstrap code that fetches and evaluates the static resource. This approach has no practical code-size limit (Static Resources support up to 5 MB per file) but requires the static resource to be deployed as part of every plugin release — a build and deployment discipline change that must be documented.

Calculate Quote API Is Not a Performance Bypass

The SBQQ.ServiceRouter Calculate Quote API (SBQQ.ServiceRouter.load('SBQQ.QuoteAPI.Calculate', ...)) runs quote calculation programmatically. It is commonly mistaken for a high-performance batch path. It is not — it runs at the same async speed as the UI path and is subject to the same governor limits on large quotes. Enabling Large Quote Mode affects both the UI and the API paths. The API is useful for automation and integration, not for circumventing calculation limits.

Common Patterns

Pattern 1: Enabling Large Quote Mode With UX Coordination

When to use: Quote line counts frequently exceed 150–200 lines, causing QLEx timeouts or governor limit errors during calculation.

How it works:

1. Navigate to CPQ Package Settings > Large Quote Options.
2. Set "Large Quote Mode" to Enabled.
3. Set the threshold to the line count above which async mode should activate (start with 150 if unsure; tune based on governor error frequency).
4. Optionally enable SBQQ__LargeQuote__c on specific accounts where all quotes should be async regardless of line count.
5. Update the QLE save button label or add a custom notification to inform reps that calculation is running asynchronously.
6. Add a process to monitor Apex jobs for failed calculation queue entries.

Why not the alternative: Leaving synchronous mode in place and trying to optimize Apex limits on the calculation path (adding custom indexes, trimming price rules) provides incremental gains but cannot overcome the fundamental CPU and SOQL limits that fire at scale.

Pattern 2: Auditing and Correcting QCP Field Declarations

When to use: QCP is returning unexpected null values for fields, or calculation is slower than expected on mid-size quotes (50–150 lines).

How it works:

1. Extract the current fieldsToCalculate and lineFieldsToCalculate arrays from the QCP source.
2. Search the plugin code for every field API name referenced in record.* or quoteModel.* expressions.
3. Build a new declaration list containing exactly those fields.
4. Compare old list vs new list: remove any field not referenced; add any field referenced but missing.
5. Deploy the updated plugin to a sandbox and validate with a representative large quote that all pricing logic produces correct results.
6. Monitor calculation time on a set of test quotes before and after to confirm payload reduction.

Why not the alternative: Declaring all fields "to be safe" is a common shortcut that degrades performance at scale and masks logic bugs where the plugin accidentally depends on fields that should not be in scope.

Pattern 3: Migrating QCP Code to Static Resource

When to use: SBQQ__Code__c is approaching or has exceeded 131,072 characters, or deployment of plugin updates is failing due to field size limits.

How it works:

1. Extract the full plugin JavaScript into a new Static Resource (e.g., QuoteCalculatorPlugin.js).
2. In SBQQ__Code__c, retain only the bootstrap loader:

   // Bootstrap: load QCP from Static Resource
   var resourceUrl = '/resource/QuoteCalculatorPlugin';
   var xhr = new XMLHttpRequest();
   xhr.open('GET', resourceUrl, false);
   xhr.send(null);
   eval(xhr.responseText);
   

3. Include the Static Resource in every Salesforce DX package version and change set that includes a plugin update.
4. Document the deployment order: Static Resource must be deployed before or alongside the SBQQ__CustomScript__c record.
5. Validate in sandbox: open the QLE on a test quote and confirm the plugin loads correctly via browser console.

Why not the alternative: Splitting logic across multiple inline scripts or compressing code to stay under the character limit produces unmaintainable code and does not scale.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Establish baseline: Record current quote line counts, average calculation time, and frequency of governor errors. Identify the threshold at which errors begin. Pull CPQ Package Settings to confirm current Large Quote Mode status and threshold value.
2. Audit QCP field declarations: If a QCP is in use, compare declared fields against all field references in plugin code. Produce a corrected declaration list. Fix underdeclared fields immediately — they produce silent wrong prices.
3. Assess SBQQ__Code__c size: Check the current character count of SBQQ__Code__c. If it exceeds 100,000 characters, plan a migration to Static Resource architecture before the next plugin update.
4. Enable Large Quote Mode if needed: If quotes exceed 150 lines and governor errors are occurring, enable Large Quote Mode. Set the threshold conservatively and document the async UX change for end users and sales operations.
5. Communicate UX change to reps: Prepare user guidance describing the async calculation indicator, expected wait time, and that quotes cannot be saved during active calculation. Coordinate with the sales ops team before production enablement.
6. Validate in sandbox: Run a set of representative large quotes through the full calculation cycle. Confirm correct prices, no null field errors, and successful save. Check the Apex job queue for any failed calculation jobs.
7. Monitor in production: After enablement, monitor Apex job queue for calculation failures, track average calculation time, and confirm governor error frequency drops. Tune the Large Quote Mode threshold if necessary.

Review Checklist

Run through these before marking work in this area complete:

• Large Quote Mode threshold is set and tuned to the actual quote volume distribution (not left at the default 100 without review)
• QCP field declarations match exactly the fields the plugin reads and writes — no over-declaration, no under-declaration
• SBQQ__Code__c character count is below 131,072; if approaching the limit, Static Resource migration is planned
• Sales reps and sales operations have been informed of async calculation UX change before production enablement
• Apex job queue monitoring is in place for failed calculation jobs
• Calculate Quote API usage in batch jobs is accounted for — Large Quote Mode affects the API path as well

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Large Quote Mode Is Not Quote-Level — It is controlled by the CPQ Package Settings threshold and the SBQQ__LargeQuote__c Account field. There is no per-quote toggle. Turning it on affects all quotes above the threshold across the org.
2. Undeclared QCP Fields Return Null, Not an Error — If a field is missing from fieldsToCalculate or lineFieldsToCalculate, the plugin receives null for that field. No exception is thrown. Pricing logic silently computes wrong values. This is the most common source of subtle QCP bugs.
3. Calculate Quote API Shares Governor Limits — Using the SBQQ.ServiceRouter calculate API in an Apex batch job does not bypass CPQ calculation limits. It runs at the same speed and under the same governor constraints as the UI path.

Output Artifacts

Related Skills

• data/cpq-data-model — CPQ object model and field relationships; foundational for understanding which fields to declare in QCP
• apex/cpq-api-and-automation — ServiceRouter calculate API, async quote calculation patterns, and batch re-pricing
• architect/cpq-architecture-patterns — System-level CPQ architecture decisions including Large Quote Mode placement in the overall solution design
• admin/cpq-pricing-rules — Price rule volume and lookup query counts are a secondary performance factor after line count

Official Sources Used

• Large Quote Performance Settings — https://help.salesforce.com/s/articleView?id=sf.cpq_large_quote.htm&type=5
• CPQ Quote Calculation Stages — https://help.salesforce.com/s/articleView?id=sf.cpq_calculation_stages.htm&type=5
• JavaScript Quote Calculator Plugin (QCP) — https://developer.salesforce.com/docs/atlas.en-us.cpq_dev_guide.meta/cpq_dev_guide/cpq_dev_jsqcp_parent.htm
• Salesforce CPQ Developer Guide: Calculate Quote API — https://developer.salesforce.com/docs/atlas.en-us.cpq_dev_guide.meta/cpq_dev_guide/cpq_dev_quote_calculator.htm