SfSkills Domains Docs GitHub

Home / devops / cpq-deployment-patterns

cpq-deployment-patterns

Deploying Salesforce CPQ configuration between environments in a CI/CD pipeline — required data record dependency order (Price Books > Products > Price Rules > Product Rules > Quote Templates), External ID cross-org matching, multi-pass deployment for self-referential lookups, CPQ metadata vs CPQ data deployment. NOT for bulk-loading the CPQ product catalog itself — use data/product-catalog-migration-cpq. NOT for record type or queue IDs that differ between orgs — use data/deployment-data-dependencies.

Open the skill folder on GitHub

CPQ Deployment Patterns

This skill activates when a practitioner needs to deploy Salesforce CPQ configuration between environments (sandbox to production, or sandbox to sandbox) as part of a CI/CD pipeline. CPQ configuration lives primarily as data records — not as metadata — and cannot be deployed with standard change sets or the Salesforce CLI Metadata API alone. This skill covers the required record load order, External ID strategy for cross-org matching, and multi-pass patterns for self-referential lookups.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

CPQ Configuration Lives as Data, Not Metadata

Standard Salesforce deployment tools (Change Sets, sf deploy, Metadata API) move Salesforce metadata (Apex classes, custom fields, page layouts). CPQ configuration records — the actual products, pricing rules, and quote templates — live in the Salesforce data layer (standard objects like Product2, Pricebook2, PricebookEntry, and CPQ custom objects like SBQQ__PricingRule__c, SBQQ__ProductRule__c).

These records must be moved using data migration tools, not metadata deployment tools. A release pipeline for CPQ orgs requires two distinct steps:

  1. Metadata deployment (Apex, LWC, custom objects, fields) — standard sf CLI or change sets
  2. Data deployment (CPQ configuration records) — SFDMU, Copado Data Deploy, Prodly, or Data Loader with External IDs

Required CPQ Data Load Order

The CPQ Quote Calculation Sequence drives the required deployment dependency order:

  1. Pricebook2 and Discount Category — No dependencies. Load first.
  2. Product2 — References Pricebook2 via PricebookEntry. Load Product2 first, then PricebookEntry.
  3. PricebookEntry — References Product2 and Pricebook2. Both must exist.
  4. SBQQ__PricingRule__c (Price Rules) — May reference Products and Price Books. Load after Products.
  5. SBQQ__ProductRule__c (Product Rules) — References Products and may reference Pricing Rules. Load after both.
  6. SBQQ__QuoteTemplate__c (Quote Templates) — May reference Product Records and Line Item fields. Load last.

Loading in any other order produces INVALID_CROSS_REFERENCE_KEY errors for records with unresolved foreign keys.

External IDs for Cross-Org Record Matching

Record IDs (18-character Salesforce IDs) are org-specific — the same logical CPQ Product has a different ID in sandbox vs. production. Cross-org data deployment requires an External ID field as the cross-org matching key:

Multi-Pass Deployment for Self-Referential Lookups

Some CPQ objects have self-referential lookups (e.g., Option Groups with parent Option Group). Single-pass loads fail because the parent record doesn't exist yet when the child record is being inserted. The multi-pass pattern:

  1. Insert all records with the self-reference field set to null
  2. Update the self-reference field in a second pass once all records exist

SFDMU handles this automatically with its selfParentExternalIdFieldName configuration. Manual approaches require two separate load operations.

Common Patterns

Pattern 1: Full CPQ Configuration Deployment via SFDMU

When to use: Moving a full CPQ configuration set (all Price Books, Products, Rules, Templates) from sandbox to production.

How it works:

  1. Configure SFDMU export.json with the CPQ objects in the required load order
  2. Set External ID fields as upsert matching keys for each object
  3. Set parent reference fields to use External ID resolution (e.g., "SBQQ__Product__r.CPQ_External_Id__c")
  4. Run SFDMU: sf data:export:tree from source, then sf data:import:tree to target
  5. Validate with SOQL: confirm record counts and key relationship traversals

Pattern 2: Incremental CPQ Configuration Update

When to use: Adding new products or price rules to an existing production org without re-deploying the full catalog.

How it works:

  1. Identify new or changed records since last deployment (filter by LastModifiedDate or a deployment flag)
  2. Export only the delta records in dependency order
  3. Upsert using External IDs — existing records are updated, new records are inserted
  4. Validate that new records are correctly associated with existing parent records

Decision Guidance

SituationRecommended ApproachReason
First-time full CPQ config deploymentSFDMU full export/import with External IDsHandles all CPQ objects with dependency ordering
Incremental product/rule additionSFDMU incremental upsert with External IDsAvoids full re-deployment for small changes
Self-referential lookup objectsMulti-pass: insert null → update referenceSingle-pass fails because parent doesn't exist yet
CPQ metadata (custom objects/fields)Standard sf CLI deployMetadata and data are separate deployment steps
Using change sets for CPQ config dataNot supported — change sets deploy metadata onlyCPQ config is data, not metadata
  1. Confirm External ID field availability — Verify a custom External ID field exists on all CPQ objects in both source and target orgs. Populate the External ID in the source org if it is empty.
  2. Document the load order — Map out all CPQ objects to deploy and their dependencies. Follow: Pricebook2 > Product2 > PricebookEntry > Price Rules > Product Rules > Quote Templates.
  3. Export configuration from source — Use SFDMU or Data Loader to extract records in dependency order with External ID values included.
  4. Validate extracted data — Confirm External ID coverage (no blanks), confirm parent IDs reference valid records, confirm the record count matches source.
  5. Deploy to target in load order — Use SFDMU or Data Loader upsert with External ID matching keys. Process objects one at a time in dependency order.
  6. Handle self-referential records — For objects with self-references, use SFDMU's selfParentExternalIdFieldName or implement a two-pass manual approach.
  7. Validate post-deployment — Run SOQL to confirm record counts, confirm Price Rule and Product Rule associations to Products, run a test CPQ quote in the target org to confirm calculation behavior.

Review Checklist

Salesforce-Specific Gotchas

  1. Change sets and sf deploy cannot move CPQ configuration data — These tools deploy metadata. CPQ configuration records are data. A release pipeline that deploys only the metadata artifact succeeds but leaves CPQ configuration missing in the target org. CPQ data deployment is a required separate pipeline step.
  2. Record IDs are org-specific — hardcoded IDs cause INVALID_CROSS_REFERENCE_KEY — Product IDs, Price Book IDs, and Rule IDs from the source org are different in the target org. Any CPQ data plan that hardcodes source org IDs will fail with INVALID_CROSS_REFERENCE_KEY errors at load time. External ID fields are the only safe cross-org reference mechanism.
  3. Self-referential CPQ lookups fail on single-pass load — Objects like Option Groups with parent-child self-references cannot be loaded in a single pass because the parent record doesn't exist when the child record is being inserted. Multi-pass is mandatory for these objects.

Output Artifacts

ArtifactDescription
CPQ data deployment load order planObject sequence with dependency documentation
SFDMU export.json configurationSFDMU config file for CPQ objects with External ID and parent resolution
External ID population scriptData Loader or SOQL-based script to populate External IDs in source org
Validation SOQL setQueries to confirm record counts and relationship integrity post-deployment

Package files