Cpq Architecture Patterns

CPQ Architecture Patterns

This skill activates when designing the overall architecture of a Salesforce CPQ implementation — covering bundle structure, pricing engine behavior and limits, multi-currency handling strategy, QCP plugin design, and external system integration. Use it before configuration begins to establish the constraints and patterns that will govern the entire CPQ build.

Before Starting

Gather this context before working on anything in this domain:

• Confirm CPQ package version installed (SBQQ managed package) — behavior differs between major versions.
• Determine expected maximum quote line items per quote. The Quote Line Editor (QLE) cannot reliably save quotes beyond 200–300 line items; this is a hard architectural limit that drives bundling, Large Quote Mode, and integration decisions.
• Determine whether multi-currency is enabled in the org and whether dated exchange rates are required — CPQ does not natively support dated exchange rates.
• Identify all external systems that will read or write quote, product, or order data — external DML on SBQQ objects bypasses the pricing engine entirely.
• Clarify whether Quote Calculator Plugin customization is needed and how complex it will be — the SBQQ__Code__c field is capped at 131,072 characters.

Core Concepts

The Fixed Pricing Waterfall

CPQ calculates prices in a strict, non-configurable sequence defined by Salesforce:

1. List Price — base price from the pricebook
2. Contracted Price — overrides list price for a specific account if a contracted price record exists
3. Block Price — overrides all prior prices if block pricing is configured for the product
4. Discount Schedules — volume or term-based discounts applied after block pricing
5. Price Rules — declarative or formula-driven price adjustments
6. Net Price — final calculated price visible on the quote line

This sequence is fixed. Architects cannot reorder stages. Any customization that attempts to modify a price "before" a later stage has already run will produce incorrect results. Price Rules, despite their power, always run after Discount Schedules — architects who design multi-stage discount logic must account for this ordering.

Quote Line Editor (QLE) Line Item Limits

The QLE is a Lightning component that renders all quote lines in the browser and performs synchronous calculations. At 200–300 line items, quote save operations become unreliable due to Apex CPU time limits, governor limits on SOQL/DML, and browser payload size. This is not a configurable limit — it is a consequence of how the QLE executes the pricing engine synchronously.

Architectural responses to this constraint:

• Bundle consolidation: Reduce visible line items by grouping features into bundle components with SBQQ__Hidden__c = true on sub-components.
• Large Quote Mode: Salesforce CPQ supports an asynchronous calculation mode that moves pricing to a server-side batch job. This changes the UX significantly — users do not see real-time price feedback — and must be explicitly communicated to stakeholders before enabling.
• External quote generation: For very high line count use cases (500+), quotes may be assembled and priced via API using ServiceRouter rather than through the QLE.

Quote Calculator Plugin (QCP) Architecture

The QCP is a JavaScript escape hatch that allows custom pricing logic to run inside the CPQ pricing engine. It is stored in the SBQQ__Code__c field on the SBQQ__CustomScript__c object. That field has a hard cap of 131,072 characters. For any non-trivial plugin:

• Store the full JavaScript in a Static Resource.
• In SBQQ__Code__c, write a minimal loader that calls fetch() against the Static Resource URL and eval()s the response.
• This pattern preserves the field limit while allowing arbitrarily large and maintainable plugin code.
• Static Resource approach also enables version-controlled deployments via metadata API.

QCP functions run asynchronously; all pricing callbacks must return Promises. Blocking patterns or synchronous-style code will cause silent failures.

Multi-Currency Storage and Limitations

When multi-currency is enabled in a CPQ org, all CPQ price fields (list price, unit price, net price) are stored in the org's corporate currency. Currency conversion to the quote's transaction currency happens at display time using the static exchange rate configured in the org.

CPQ does not natively support dated exchange rates. If a customer requires that prices use the exchange rate in effect at a specific date (e.g., contract signature date), there is no out-of-box mechanism. Documented workarounds include:

• Creating separate pricebooks per currency with hard-coded converted prices — eliminates dynamic conversion entirely.
• Custom Apex that recalculates prices at quote activation using a custom exchange rate table.

Architects must surface this limitation explicitly when multi-currency and financial accuracy requirements coexist.

Common Patterns

Pattern: Flat Bundle vs. Nested Bundle Design

When to use flat bundles: Single-level product groupings where all components belong to the same parent, no sub-grouping required, and QLE performance is a concern. Flat bundles (1 parent, N components with SBQQ__FeatureName__c grouping) are simpler to maintain, easier to price, and have lower QLE rendering cost.

When to use nested bundles: When the product genuinely has distinct tiers — e.g., a base platform product with sub-bundle hardware options and a separate sub-bundle for software licenses. Nested bundles increase quote line count and QLE complexity. Each additional nesting level multiplies the SOQL calls during calculation.

Constraint: Deeply nested bundles (3+ levels) frequently cause pricing engine timeouts. Prefer flat bundles with Option Constraints to simulate grouping behavior without additional nesting.

Option Constraints (SBQQ__OptionConstraint__c) enforce conditional logic between product options — use them instead of nested bundles when the goal is conditional inclusion rather than genuine product hierarchy.

Pattern: Static Resource QCP for Complex Plugins

When to use: Whenever QCP JavaScript exceeds approximately 80,000 characters (safe margin below 131,072), or when the plugin requires unit-testable modular code.

How it works:

1. Write the full plugin JavaScript in a Static Resource (e.g., CPQCalculatorPlugin).
2. In SBQQ__Code__c, deploy a loader:

(function() {
  var resourceUrl = '/resource/CPQCalculatorPlugin';
  var xhr = new XMLHttpRequest();
  xhr.open('GET', resourceUrl, false); // synchronous load at init time
  xhr.send(null);
  if (xhr.status === 200) {
    eval(xhr.responseText);
  }
})();

3. The actual plugin callbacks (onBeforeCalculate, onPriceRules, etc.) are defined in the Static Resource.
4. Deploy via StaticResource metadata type — no manual copy-paste into the org field.

Why not inline: Field character limit will silently truncate code, causing the plugin to fail with cryptic errors. The truncation point is not surfaced in validation.

Pattern: External System Integration via ServiceRouter

When to use: Any time an external system (ERP, billing platform, subscription management) needs to create, update, or read CPQ quotes, products, or calculate pricing.

How it works: Salesforce CPQ exposes a REST API at /services/apexrest/SBQQ/ServiceRouter. External systems call this endpoint with a JSON payload specifying the reader or saver class (e.g., SBQQ.QuoteService.read / SBQQ.QuoteService.save).

Why not direct DML: Writing directly to SBQQ__Quote__c, SBQQ__QuoteLine__c, or related objects via REST/SOAP API or integration user DML completely bypasses the pricing engine. Prices will not be recalculated, required fields may not be populated by triggers, and the quote will be in a corrupt state. This is the single most common architectural mistake in CPQ integrations.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on CPQ architecture:

1. Gather constraints: Collect maximum quote line count, multi-currency requirements, external system integration requirements, and estimated QCP complexity. These four inputs drive the most consequential architectural decisions.

2. Assess QLE line limit risk: If any quote scenario may produce more than 150 line items, plan for Large Quote Mode from day one. Design bundle structures to minimize visible line count — set sub-components to hidden where users do not need to interact with them.

3. Design bundle structure: Choose flat vs. nested bundle strategy. Document the maximum nesting depth. Default to flat with Option Constraints unless the product model requires genuine hierarchy. Validate the design against QLE rendering cost before configuration begins.

4. Plan QCP architecture: Determine whether a QCP is needed. If yes, estimate JavaScript size. If likely to exceed 80,000 characters, plan the Static Resource loader pattern from the start — retrofitting this pattern after QCP is live requires a deployment freeze.

5. Define multi-currency strategy: If multi-currency is enabled, document whether dated exchange rates are a business requirement. If yes, design the workaround (pricebook-per-currency or custom Apex rate table) and surface it as a scope item — this is not a configuration-only solution.

6. Define integration touchpoints: For each external system, identify whether it reads or writes CPQ data. Mandate ServiceRouter for all write operations. Provide the external system team with the ServiceRouter API documentation and confirm they will not use direct DML.

7. Validate and review: Run scripts/check_cpq_architecture.py against the metadata directory. Review checklist items. Confirm Large Quote Mode decision is documented and communicated to project stakeholders if applicable.

Review Checklist

Run through these before marking CPQ architecture work complete:

• Maximum quote line count scenario documented; Large Quote Mode decision made and communicated
• Bundle nesting depth confirmed at 2 levels or fewer, or documented exception with mitigation
• QCP JavaScript size estimated; Static Resource pattern adopted if >80K characters
• Multi-currency dated exchange rate requirement surfaced and resolution documented
• All external integration touchpoints confirmed to use ServiceRouter — no direct DML paths
• Pricing waterfall stage ordering reviewed against all pricing requirements (List → Contracted → Block → Discount Schedules → Price Rules → Net)
• Large Quote Mode UX impact communicated to stakeholders if enabled

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. QCP field truncation is silent — If SBQQ__Code__c content exceeds 131,072 characters, Salesforce truncates it without error. The plugin appears to save successfully but executes truncated/broken JavaScript. The failure manifests as incorrect pricing or no pricing, with no clear error message pointing to truncation.

2. Direct DML on SBQQ objects corrupts quotes — Writing to CPQ objects via external API (REST, SOAP, integration user) bypasses all CPQ triggers and the pricing engine. Quote lines will show stale or zero prices, required calculated fields will be empty, and the quote cannot be reliably activated. There is no automated warning when this happens.

3. Discount Schedules always run before Price Rules — The waterfall sequence is fixed. A Price Rule that sets a price field will run after Discount Schedules have already applied. Architects who expect Price Rules to set a "base" price before volume discounts apply will get incorrect results. Design Price Rules to adjust net price, not reset it.

4. Large Quote Mode disables real-time pricing feedback — When SBQQ__LargeQuote__c is set on an Account or enabled globally, the QLE no longer recalculates prices as users edit lines. Users must trigger calculation manually. This is a significant UX regression that must be communicated and trained on before go-live.

5. Multi-currency exchange rate is static at display time — CPQ converts corporate-currency prices to transaction currency using the org's current exchange rate. If the org exchange rate changes after a quote is created, the displayed price changes retroactively. There is no snapshot of the rate at quote creation time unless custom code captures it.

Output Artifacts

Related Skills

• pricing-model-design — Use to design the specific pricing method, discount schedule, and block pricing configuration after the CPQ architecture is established
• cpq-pricing-rules — Use to implement individual Price Rule objects, Price Conditions, and Price Actions within the architecture defined here
• cpq-product-catalog-setup — Use to configure product bundles and Product Options after the bundle design pattern is decided
• multi-currency-sales-architecture — Use alongside this skill when the org-wide multi-currency architecture involves CPQ; covers broader currency enablement decisions
• integration-framework-design — Use for the broader integration architecture when CPQ ServiceRouter is one of multiple integration touchpoints