Commerce Order History Migration

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:

• Salesforce Order Management uses a strict object creation sequence: Order (Status=Draft) → OrderDeliveryGroup → OrderItem → Order activation → OrderSummary via ConnectAPI or Flow core action.
• OrderSummary cannot be created via direct DML insert, Bulk API, or Data Loader. Attempting to do so either fails silently or raises an error depending on the API version.
• Historical orders that are no longer being serviced should use LifeCycleType = Unmanaged. Unmanaged OrderSummaries disable the refund, cancel, and fulfillment core actions, which is correct for historical data.
• This skill covers Salesforce Order Management (the Order object on the CRM platform), not B2C Commerce Cloud legacy order objects in a separate SaaS system.

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:

• Managed — Standard active order lifecycle: supports fulfillment, cancel, refund, and change order core actions. Use for orders that are still being processed.
• Unmanaged — Historical order marker: disables fulfillment, cancel, refund, and change order core actions. Use for historical orders that are no longer being serviced. This is the correct value for order history migration.

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:

• ConnectAPI (Apex): ConnectAPI.OrderSummary.createOrderSummary(orderSummaryInput) where orderSummaryInput is a ConnectAPI.OrderSummaryInputRepresentation
• Flow Core Action: "Create Order Summary" standard core action in Flow Builder

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

Recommended Workflow

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

• Order created in Draft status before OrderDeliveryGroup and OrderItem are inserted
• Order activated before OrderSummary creation attempt
• OrderSummary created via ConnectAPI or Flow core action — not via direct DML or Bulk API
• LifeCycleType = Unmanaged set for historical orders
• SOQL validation confirms OrderSummary exists for every migrated Order
• No fulfillment or refund actions triggered on historical OrderSummary records post-migration

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

Related Skills

• data/product-catalog-migration-commerce — For migrating B2B Commerce product catalog data
• devops/cpq-deployment-patterns — For CPQ-specific order and billing configuration deployment
• apex/commerce-order-api — For Apex-level Order Management API integration patterns