Historical Order Migration

Historical Order Migration

This skill activates when a practitioner needs to load historical order, contract, subscription, and asset data into an org running Salesforce CPQ (SBQQ) so that future renewal and amendment processes work correctly. It covers the CPQ Legacy Data Upload mechanism — the only supported path for this use case — and the strict object sequencing, field requirements, and configuration gates that govern it.

Before Starting

Gather this context before working on anything in this domain:

• Confirm contract-based renewal model: CPQ Legacy Data Upload is only supported when the CPQ org uses the contract-based renewal model (SBQQ__RenewalModel__c = Contract Based on the CPQ package settings custom setting). Asset-based renewal model orgs cannot use this mechanism. Confirm the setting before any load begins.
• Disable CPQ price and product rules: CPQ triggers price rules and product rules on every Quote and Quote Line save. These rules fire during data load and cause incorrect pricing calculations, field overwrites, or load failures. The rules must be disabled before any Legacy Data Upload records are inserted and re-enabled only after the full load is validated.
• Batch size must be 1: CPQ Legacy Data Upload requires a batch size of 1 for all inserted objects. Loading with batch size > 1 bypasses required CPQ calculation triggers and produces records that look correct in the data but fail silently at renewal time. This applies to all tools: Data Loader, Bulk API, any ETL platform.
• Asset Root Id and Revised Asset field interaction: SBQQ__Asset__c.SBQQ__RootId__c must be null if SBQQ__Asset__c.SBQQ__RevisedAsset__c is populated. Populating both fields simultaneously produces records that look correct but corrupt the renewal/amendment chain silently. The corruption surfaces only at the first renewal attempt, not at insert time.
• Required CPQ fields for renewal readiness: SBQQ__Subscription__c records must have correct values for SBQQ__StartDate__c, SBQQ__EndDate__c, SBQQ__Quantity__c, SBQQ__NetPrice__c, SBQQ__RegularPrice__c, SBQQ__Product__c, and SBQQ__Contract__c. Missing or incorrect values on any of these fields cause renewal quote generation to produce blank or miscalculated lines.

Core Concepts

CPQ Legacy Data Upload — What It Is and Why It Is Required

CPQ Legacy Data Upload is Salesforce's designated mechanism for inserting historical order and contract data in a way that supports future renewals and amendments. It is not a standard data migration approach — it is a controlled insert process that triggers specific CPQ calculation hooks on each record.

Without Legacy Data Upload, records inserted via standard Bulk API or Data Loader bypass the CPQ package's renewal-preparation logic. The resulting subscriptions and assets may appear correct in the data but do not have the internal field values that CPQ requires to generate accurate renewal quotes. This failure mode is silent: no error is thrown at load time; the problem surfaces only when the first renewal opportunity is created.

Legacy Data Upload is only available for orgs on the contract-based renewal model. Orgs using asset-based renewals have a different renewal mechanism that does not rely on SBQQ__Subscription__c records in the same way.

Object Load Sequence

CPQ enforces referential integrity and triggers package logic in a strict sequence. The required load order for historical CPQ data is:

1. Account — must exist before any other record; typically already present
2. Opportunity — required as the parent of SBQQ__Quote__c if the source data includes opportunity records
3. Product2 / SBQQ__Product__c — must exist before Quote Lines can reference them
4. SBQQ__Quote__c (CPQ Quote) — must be inserted with SBQQ__Status__c = Approved and SBQQ__Primary__c = true; the approved primary quote is what CPQ uses to create the Contract
5. SBQQ__QuoteLine__c (CPQ Quote Line) — must be inserted after the parent Quote exists
6. Contract — the standard Salesforce Contract object; must reference the Account; SBQQ will link it to the Quote via SBQQ__Quote__c on the Contract
7. SBQQ__Subscription__c — references both the Contract and the Product; contains the subscription term, pricing, and quantity data that drives renewal generation
8. SBQQ__Asset__c — references the Account and optionally the Subscription; required for amendment workflows

Any deviation from this sequence produces orphaned child records that either fail at insert or produce broken renewal chains.

SBQQ__Quote__c Required Fields for Legacy Upload

The CPQ Quote inserted during Legacy Data Upload is not a working salesperson quote — it is a historical record that establishes the approved configuration. Required fields:

• SBQQ__Status__c = Approved
• SBQQ__Primary__c = true
• SBQQ__Account__c = the parent Account Id
• SBQQ__Opportunity2__c = the parent Opportunity Id (if applicable)
• SBQQ__StartDate__c and SBQQ__EndDate__c matching the contract term
• SBQQ__SubscriptionTerm__c = numeric term in months

A Quote that is not Approved and Primary will not be correctly linked to its Contract by CPQ's renewal logic.

SBQQ__Subscription__c — The Renewal Engine

SBQQ__Subscription__c records are the core of the CPQ renewal model. When a renewal opportunity is created, CPQ reads the active subscriptions on the expiring contract and generates renewal quote lines from them. The accuracy of the renewal quote is entirely dependent on the accuracy of the subscription records.

Key fields that drive renewal quote line generation:

• SBQQ__StartDate__c / SBQQ__EndDate__c — defines the subscription term; renewal start date is derived from the subscription end date
• SBQQ__Quantity__c — quantity carried into the renewal
• SBQQ__RegularPrice__c / SBQQ__NetPrice__c / SBQQ__CustomerPrice__c — pricing fields used to calculate renewal price depending on the org's renewal pricing method
• SBQQ__RenewalQuantity__c — if populated, overrides Quantity for renewal purposes
• SBQQ__Contract__c — parent contract reference; this is how CPQ discovers which subscriptions belong to the renewing contract
• SBQQ__Product__c — the CPQ product; must match an active Product2/SBQQ__Product__c record

Common Patterns

Pattern: Full Legacy Data Upload for Contract-Based Renewal Org

When to use: The org uses contract-based renewals and historical orders from a legacy system need to be loaded so that CPQ generates correct renewal quotes at the end of the original subscription term.

How it works:

1. Disable CPQ price rules and product rules via CPQ package settings (or use SBQQ__DisableAmendmentCoterminusCheck__c and related settings depending on org version).
2. Set Data Loader / Bulk API batch size to 1 for all CPQ objects in this load.
3. Insert SBQQ__Quote__c records: Status = Approved, Primary = true, correct Account/Opportunity references, subscription term dates.
4. Insert SBQQ__QuoteLine__c records referencing the parent Quote and the correct Product2/SBQQ__Product__c.
5. Insert Contract records referencing Account; populate SBQQ__Quote__c on the Contract to link it to the approved CPQ quote.
6. Insert SBQQ__Subscription__c records referencing the Contract and Product; populate all pricing and term fields accurately.
7. Insert SBQQ__Asset__c records if amendments will be used; ensure SBQQ__RootId__c is null when SBQQ__RevisedAsset__c is populated.
8. Re-enable CPQ price and product rules.
9. Run post-load validation: query subscriptions by contract, verify term dates and pricing fields, test renewal quote generation in sandbox.

Why not load with standard Bulk API at default batch size: CPQ's package triggers that prepare subscription records for renewal fire only when batch size is 1. Higher batch sizes cause the triggers to fire in bulk mode and skip renewal-preparation logic, producing records that appear correct in queries but generate blank or incorrectly priced renewal quote lines.

Pattern: Subscription-Only Load for Orgs with Existing Contracts

When to use: The target org already has Account, Opportunity, and Contract records loaded via a prior migration wave. Only CPQ Subscriptions and Assets need to be added to enable renewal generation.

How it works:

1. Confirm all parent Contracts exist and are in Activated status.
2. Disable CPQ price and product rules.
3. Set batch size to 1.
4. Insert SBQQ__Subscription__c with SBQQ__Contract__c referencing existing Contract external IDs.
5. Validate subscription count per contract matches source system subscription line count.
6. Insert SBQQ__Asset__c if amendment support is needed.
7. Re-enable rules.
8. Spot-test renewal quote generation on one or more contracts before proceeding to production load.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Verify prerequisites: Confirm the org is on contract-based renewal model (SBQQ__RenewalModel__c). Confirm all parent records (Accounts, Opportunities, Products) exist in the target org. Document the load sequence and assign external ID fields to every CPQ object that needs cross-reference resolution.
2. Disable CPQ automation: Disable price rules and product rules via CPQ package settings before inserting any records. Record the current settings so they can be restored exactly after the load completes.
3. Load Quotes then Quote Lines at batch size 1: Insert SBQQ__Quote__c with Status = Approved and Primary = true. Then insert SBQQ__QuoteLine__c. Verify record counts after each step before proceeding.
4. Load Contracts and link to Quotes: Insert or upsert Contract records. Populate SBQQ__Quote__c on each Contract to link it to the approved CPQ quote. Set Contract Status to Activated if the subscription term has started.
5. Load Subscriptions at batch size 1: Insert SBQQ__Subscription__c with all required pricing and term fields populated. Verify every subscription has a non-null SBQQ__Contract__c, SBQQ__Product__c, SBQQ__StartDate__c, SBQQ__EndDate__c, and SBQQ__Quantity__c.
6. Load Assets (if amendments required): Insert SBQQ__Asset__c. For revised assets, populate SBQQ__RevisedAsset__c and leave SBQQ__RootId__c null. For root (original) assets, confirm SBQQ__RootId__c references the asset's own Id (set by CPQ post-insert) or is null.
7. Re-enable CPQ automation and validate: Re-enable price and product rules. Run post-load validation queries (see Review Checklist). Test renewal quote generation on a sample of contracts in a sandbox before declaring the migration complete.

Review Checklist

Run through these before marking historical CPQ order migration complete:

• Org confirmed on contract-based renewal model before any load began
• CPQ price rules and product rules disabled before first insert
• Batch size set to 1 for all CPQ object loads (Quote, Quote Line, Subscription, Asset)
• All SBQQ__Quote__c records have Status = Approved and Primary = true
• All SBQQ__Subscription__c records have non-null SBQQ__Contract__c, SBQQ__Product__c, SBQQ__StartDate__c, SBQQ__EndDate__c, SBQQ__Quantity__c
• SBQQ__Asset__c records with SBQQ__RevisedAsset__c populated have SBQQ__RootId__c = null
• Contract records are in Activated status where the subscription term has begun
• CPQ price rules and product rules re-enabled after load completed
• Post-load validation query: subscription count per contract matches source
• Test renewal quote generation triggered on at least one contract in sandbox

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Batch size > 1 silently breaks renewals — Loading CPQ Subscriptions or Assets with batch size greater than 1 causes CPQ's package triggers to run in bulk mode, skipping the renewal-preparation logic. The records insert without error and look correct in SOQL queries. The silent corruption surfaces only when the first renewal opportunity is created — typically months after the migration.

2. SBQQ__Asset__c Root Id and Revised Asset mutual exclusivity — SBQQ__RootId__c must be null if SBQQ__RevisedAsset__c is populated. Populating both fields does not cause an insert error; CPQ accepts the record. The corruption appears at the first amendment or renewal: CPQ follows both the root chain and the revised chain and creates duplicate or malformed amendment quote lines.

3. CPQ Legacy Data Upload requires contract-based renewal model — The Legacy Data Upload process is only defined and tested for the contract-based renewal model. Asset-based renewal orgs have a different internal mechanism for renewal generation. Using Legacy Data Upload procedures in an asset-based renewal org produces subscriptions that do not participate in renewal generation.

4. Price and product rules fire during load if not disabled — CPQ price rules execute on every Quote and Quote Line insert/update, even during data loads. A price rule that recalculates net price based on discount schedules will overwrite the historically correct price being loaded from the source system. Rules must be disabled before load, not just during Quote insert — they can fire again on Subscription and Asset saves via triggered flows.

5. SBQQ__Quote__c Status and Primary flags are required, not cosmetic — A CPQ Quote that is not Approved and Primary does not participate in the Contract-to-Quote linkage that CPQ uses during renewal generation. Inserting a historical Quote with Status = Draft produces a record that looks like a valid quote but is invisible to CPQ's renewal engine. The Contract will not produce correct renewal quotes because no approved primary quote is linked to it.

6. Contract must be Activated before subscriptions are used in renewal — SBQQ__Subscription__c records on a Contract that is in Draft status are not treated as active subscriptions by CPQ's renewal engine. If historical contracts are left in Draft after the migration, renewal opportunity generation will not fire for them at the end of the subscription term.

Output Artifacts

Related Skills

• opportunity-pipeline-migration — use when migrating standard Opportunity records and OpportunityLineItems; does not cover CPQ-specific objects
• data-migration-planning — use for multi-object migration architecture, tool selection, external ID strategy, and rollback planning
• cpq-data-model — use to understand the CPQ object schema, field dependencies, and package behavior before designing the migration
• bulk-api-and-large-data-loads — use for Bulk API 2.0 job configuration, monitoring, and error handling mechanics

Official Sources Used

• CPQ Legacy Data Upload — https://help.salesforce.com/s/articleView?id=sf.cpq_legacy_data_upload.htm&type=5
• Legacy Data Upload with Renewals and Amendments (KA-000384279) — https://help.salesforce.com/s/articleView?id=000384279&type=1
• SBQQ__Subscription__c Object Fields for Legacy Upload — https://help.salesforce.com/s/articleView?id=sf.cpq_subscription_fields.htm&type=5
• Salesforce CPQ Developer Guide — https://developer.salesforce.com/docs/atlas.en-us.cpq_dev_guide.meta/cpq_dev_guide/cpq_dev_guide.htm
• Bulk API 2.0 Developer Guide — https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/asynch_api_intro.htm