SfSkills Domains Docs GitHub

Home / data / commerce-order-history-migration

commerce-order-history-migration

Use when migrating historical order records into Salesforce Order Management — covers the required object creation sequence (Order > OrderDeliveryGroup > OrderItem > OrderSummary), LifeCycleType=Unmanaged for historical orders, and OrderSummary creation via ConnectAPI. NOT for CPQ legacy order, contract and asset upload using SBQQ objects — use data/historical-order-migration. NOT for live order processing, fulfilment, returns or cancellations — use admin/commerce-order-management.

Open the skill folder on GitHub

Commerce Order History Migration

This skill activates when a practitioner needs to migrate historical order records into Salesforce Order Management. It provides the mandatory object creation sequence, explains why OrderSummary cannot be created via direct DML insert, and covers the LifeCycleType=Unmanaged setting for historical orders that disables refund and fulfillment core actions.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Mandatory Object Creation Sequence

Salesforce Order Management enforces referential integrity through a strict creation order:

  1. Order (Status = Draft) — The parent order record. Must be in Draft status before child records are added.
  2. OrderDeliveryGroup — Delivery grouping: shipping address, delivery method. Must reference a valid Order in Draft status.
  3. OrderItem — Line items referencing the Order and OrderDeliveryGroup. Product and pricing data.
  4. Order activation — Change Order Status from Draft to Activated. This commits the order and enables OrderSummary creation.
  5. OrderSummary — Created via ConnectAPI.OrderSummaryInputRepresentation in Apex, or via the "Create Order Summary" Flow core action. This is NOT a direct DML insert.

Attempting to create OrderSummary before Order activation, or via direct DML, will fail.

LifeCycleType for Historical Orders

The LifeCycleType field on OrderSummary controls which Order Management core actions are available:

Setting LifeCycleType = Unmanaged during OrderSummary creation prevents accidental refund or fulfillment actions from being triggered on historical data in Order Management.

Why OrderSummary Requires ConnectAPI or Flow

OrderSummary is not a standard DML-insertable object in the same way as Order or OrderItem. It requires platform-managed creation through:

This design ensures Order Management's internal state machine is correctly initialized for the new summary record. Bypassing ConnectAPI by inserting directly to the OrderSummary object either fails or creates a malformed record that breaks Order Management reports and actions.

Common Patterns

Pattern 1: Full Historical Order Migration with Unmanaged OrderSummary

When to use: Migrating closed or completed historical orders from a legacy system where no further fulfillment, refund, or cancellation actions are needed.

How it works:

  1. Insert Order records (Status = Draft, OrderedDate = historical date) via Bulk API
  2. Insert OrderDeliveryGroup records referencing each Order ID
  3. Insert OrderItem records referencing Order and OrderDeliveryGroup IDs
  4. Activate each Order: update Status from Draft to Activated via Bulk API update
  5. Create OrderSummary for each Order via ConnectAPI or Flow core action with LifeCycleType = Unmanaged
  6. Validate: confirm OrderSummary exists for each Order, confirm LifeCycleType = Unmanaged

Why not Bulk API to OrderSummary: OrderSummary requires ConnectAPI because the platform must initialize internal state, calculate summary totals, and set up the Order Management state machine. Direct DML bypasses this initialization.

Pattern 2: Batched OrderSummary Creation via Apex

When to use: Large volume historical order migration where manual Flow processing is impractical.

How it works:

// Called in a Batch Apex job after Orders are activated
ConnectAPI.OrderSummaryInputRepresentation input = new ConnectAPI.OrderSummaryInputRepresentation();
input.orderId = orderId;
input.orderLifeCycleType = 'UNMANAGED';
ConnectAPI.OrderSummary.createOrderSummary(input);

Run this in a Batch Apex class that queries activated Orders without existing OrderSummary records and processes them in chunks of 200 per execute() invocation to respect governor limits.

Decision Guidance

SituationRecommended ApproachReason
Historical closed orders, no future actions neededLifeCycleType = UnmanagedDisables refund/cancel/fulfillment core actions on historical records
Active orders still in fulfillmentLifeCycleType = ManagedEnables standard Order Management action menu
OrderSummary creationConnectAPI or Flow core actionCannot be created via direct DML or Bulk API
Large volume (>10,000 orders)Batch Apex calling ConnectAPIFlow core action has lower throughput than Apex batch
CPQ legacy order migrationUse CPQ-specific data migration skillSBQQ objects and contract migration require different tooling
  1. Confirm target org has Order Management enabled — Check Setup > Order Settings and confirm OrderSummary object is visible in Object Manager.
  2. Load Order records in Draft status — Insert Order records via Bulk API. Set Status = Draft and OrderedDate to the historical date. Do not activate yet.
  3. Load OrderDeliveryGroup records — Insert one or more delivery groups per Order, referencing the Order ID.
  4. Load OrderItem records — Insert line items referencing both Order ID and OrderDeliveryGroup ID.
  5. Activate Orders — Update Order Status from Draft to Activated via Bulk API update. Only activated Orders can have OrderSummary records.
  6. Create OrderSummary via ConnectAPI or Flow — For each activated Order without an existing OrderSummary, call ConnectAPI.OrderSummary.createOrderSummary() with LifeCycleType = UNMANAGED (for historical orders).
  7. Validate — Run SOQL: SELECT Id, LifeCycleType FROM OrderSummary WHERE OrderId IN :migratedOrderIds. Confirm all Orders have a corresponding OrderSummary with the correct LifeCycleType.

Review Checklist

Salesforce-Specific Gotchas

  1. OrderSummary direct DML insert fails silently in some API versions — Depending on the API version, a direct DML insert to OrderSummary either raises an error or silently creates a malformed record. Either outcome breaks Order Management functionality. Always use ConnectAPI or Flow core action.
  2. Order must be Activated before OrderSummary can be created — Attempting to call ConnectAPI.OrderSummary.createOrderSummary() for an Order that is still in Draft status raises a FIELD_INTEGRITY_EXCEPTION. Activate Orders first, then create summaries.
  3. LifeCycleType cannot be changed after OrderSummary creation — The LifeCycleType field is set at creation time and is immutable. Setting the wrong type during migration requires deleting and recreating the OrderSummary record, which also deletes all Order Management state associated with it.

Output Artifacts

ArtifactDescription
Load sequence planOrdered list of objects to insert with dependency documentation
ConnectAPI OrderSummary creation Apex classBatch Apex for bulk OrderSummary creation with Unmanaged lifecycle
Validation SOQL setQueries to confirm OrderSummary count, LifeCycleType, and order-summary linkage

Package files