SfSkills Domains Docs GitHub

Home / admin / commerce-order-management

commerce-order-management

Use this skill for Salesforce Order Management (OMS) tasks: order lifecycle, OrderSummary creation and status, FulfillmentOrder creation and routing, returns, exchanges, cancellations, and platform event subscriptions. Trigger keywords: order management, OrderSummary, FulfillmentOrder, ReturnOrder, ensure-funds, ensure-refunds, submit-cancel, submit-return, adjust-item-submit. NOT for split-order routing or Omnichannel Inventory design — use architect/order-management-architecture. NOT for loading historical orders — use data/commerce-order-history-migration.

Open the skill folder on GitHub

Commerce Order Management

This skill activates when a practitioner needs to set up or extend Salesforce Order Management (OMS): creating OrderSummary records from activated Orders, building FulfillmentOrder routing logic, processing cancellations and returns through Connect API actions, handling async payment jobs, and subscribing to OMS platform events. It covers only OMS-licensed orgs — it does NOT cover CPQ orders or standard Salesforce Orders outside of OMS.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Order Lifecycle in OMS

The canonical OMS object chain is:

Order (Activated)
  └── OrderSummary (OrderLifeCycleType: MANAGED | UNMANAGED)
        ├── OrderItemSummary (one per OrderItem, represents product line)
        └── OrderDeliveryGroupSummary (groups items by shipping address/method)
              └── FulfillmentOrder
                    └── FulfillmentOrderLineItem
ReturnOrder
  └── ReturnOrderLineItem

An Order must reach Status = Activated before the OMS trigger fires to create the OrderSummary. The OrderSummary represents the commercial truth of the order throughout its lifecycle and is the anchor for all downstream financial and fulfillment records.

MANAGED vs UNMANAGED OrderLifeCycleType

OrderLifeCycleType on the OrderSummary record controls whether the platform enforces Connect API usage for mutations:

This field is immutable after OrderSummary creation. Set it correctly during the Order-to-OrderSummary flow; it cannot be changed later.

Connect API Order Management Actions

All MANAGED-mode mutations are executed through named Connect API actions. Key actions:

ActionPurposeNotes
submit-cancelCancel one or more OrderItemSummary quantitiesProduces a ChangeOrder; eligible pre-fulfillment
submit-returnInitiate a return for fulfilled itemsCreates ReturnOrder + ReturnOrderLineItem records
adjust-item-submitAdjust item quantity or priceCan produce up to 3 separate ChangeOrders for pre/in/post-fulfillment splits
ensure-funds-asyncAuthorize or capture paymentEnqueued async job; errors surfaced via ProcessExceptionEvent
ensure-refunds-asyncIssue refund to customerEnqueued async job; errors surfaced via ProcessExceptionEvent

Platform Events for OMS

OMS publishes platform events at key lifecycle moments. Subscribe to these in Flow or Apex:

EventWhen it fires
OrderSummaryCreatedEventAfter an OrderSummary is created from an Order. Use to trigger downstream provisioning.
OrderSumStatusChangedEventWhen an OrderSummary's status changes (e.g., to Fulfilled, Cancelled).
FOStatusChangedEventWhen a FulfillmentOrder status changes (e.g., to Fulfilled, Cancelled).
ProcessExceptionEventWhen an async job (ensure-funds-async, ensure-refunds-async) encounters an error. You must subscribe to this event — payment failures are not surfaced through standard exception handling.

Common Patterns

Pattern: Standard Fulfillment Flow

When to use: An Order has been activated and items need to be routed to a fulfillment location for picking, packing, and shipping.

How it works:

  1. Order reaches Status = Activated (manually or through a Checkout flow).
  2. OMS trigger fires; OrderSummaryCreatedEvent is published.
  3. Subscribe to OrderSummaryCreatedEvent in a triggered Flow or Apex handler.
  4. In the handler, call the OMS routing engine or a custom routing Flow to create FulfillmentOrder records grouped by location and delivery group.
  5. FulfillmentOrder starts in Draft status; transition to Activated to release to the warehouse.
  6. Subscribe to FOStatusChangedEvent to react when warehouse marks items as shipped/fulfilled.
  7. Call ensure-funds-async to capture payment once fulfillment is confirmed.

Why not the alternative: Creating FulfillmentOrder records manually via DML without routing logic leads to incorrect location assignments and breaks the OMS inventory reservation model.

Pattern: Cancellation and Return Flow

When to use: A customer wants to cancel an unfulfilled item (pre-fulfillment cancel) or return a fulfilled item.

How it works:

Pre-fulfillment cancel:

  1. Call Connect API action submit-cancel with the OrderSummaryId and a list of {orderItemSummaryId, quantity} pairs.
  2. OMS validates eligible cancel quantity and creates a ChangeOrder.
  3. Call ensure-refunds-async to issue the refund. Subscribe to ProcessExceptionEvent for failures.

Post-fulfillment return:

  1. Call Connect API action submit-return with the OrderSummaryId and returned line items.
  2. OMS creates a ReturnOrder and ReturnOrderLineItem records.
  3. When the ReturnOrderLineItem is processed (item received), call ensure-refunds-async.

Why not the alternative: Manually updating OrderItemSummary quantities in MANAGED mode will either throw a DML exception or corrupt financial aggregates on the OrderSummary. Always use the Connect API actions.

Decision Guidance

SituationRecommended ApproachReason
Standard B2C or B2B order in OMS-licensed orgUse MANAGED OrderLifeCycleTypeEnforces financial consistency; Connect API actions create auditable ChangeOrders
Custom order scenario that cannot fit OMS state machineUse UNMANAGED OrderLifeCycleTypeAllows direct DML; but loses OMS financial-summary automation
Item cancellation before fulfillment startssubmit-cancel Connect API actionUpdates TotalCancelled quantities and creates ChangeOrder automatically
Item return after fulfillmentsubmit-return Connect API action + ReturnOrderCreates ReturnOrder records; eligible for ensure-refunds-async
Price or quantity adjustment spanning fulfillment statusadjust-item-submitCan produce up to 3 ChangeOrders to split pre/in/post-fulfillment amounts
Payment authorization or captureensure-funds-asyncAsync job; subscribe to ProcessExceptionEvent for error handling
Refund issuanceensure-refunds-asyncAsync job; subscribe to ProcessExceptionEvent for error handling
CPQ-generated Order needing OMS processingOut of scope — CPQ Orders do not create OrderSummarySeparate license and data model required; evaluate integration patterns instead

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Verify prerequisites: Confirm OMS license is provisioned, the Order is in Activated status, and OrderLifeCycleType has been decided (MANAGED is the default for OMS implementations).
  2. Establish the OrderSummary: Ensure the Order activation triggers OrderSummary creation. Confirm that OrderLifeCycleType is set correctly before creation since it cannot be changed afterward. Subscribe to OrderSummaryCreatedEvent for downstream triggering.
  3. Configure fulfillment routing: Build or configure the routing logic (OMS routing engine or custom Flow/Apex) to create FulfillmentOrder records from OrderDeliveryGroupSummary records. Validate that FulfillmentOrders reference correct locations.
  4. Implement cancellation and return paths: Use submit-cancel for pre-fulfillment cancellations and submit-return for post-fulfillment returns. Never use direct DML on OrderItemSummary in MANAGED mode.
  5. Wire up async payment jobs: Invoke ensure-funds-async after fulfillment confirmation and ensure-refunds-async after return/cancel. Subscribe to ProcessExceptionEvent to catch and handle payment job failures.
  6. Subscribe to OMS platform events: Register event-triggered Flows or Apex for FOStatusChangedEvent, OrderSumStatusChangedEvent, and ProcessExceptionEvent to keep downstream systems synchronized.
  7. Test end-to-end in sandbox: Activate a test Order, verify OrderSummary creation, run a cancellation and a return through the Connect API, confirm ChangeOrder records are created, and verify ProcessExceptionEvent handling fires correctly.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. OrderLifeCycleType is immutable after OrderSummary creation — If MANAGED is set and later the implementation requires direct DML, there is no API to change it. The OrderSummary must be deleted and recreated, which can orphan related financial records. Plan the lifecycle type carefully before go-live.
  2. Direct DML on OrderItemSummary in MANAGED mode silently corrupts totals — Updating QuantityCanceled or TotalPrice directly via Apex DML does not raise a reliable exception in all API versions; in some cases it succeeds but leaves the OrderSummary aggregate fields (TotalAdjustedProductAmount, etc.) in an inconsistent state that cannot be repaired without support.
  3. ProcessExceptionEvent is the only error signal from async payment jobs — ensure-funds-async and ensure-refunds-async are enqueued Queueable jobs. They do not throw exceptions to the calling context, and they do not log to standard Apex debug logs by default. If no ProcessExceptionEvent subscriber exists, payment failures are invisible at runtime.
  4. adjust-item-submit produces up to 3 ChangeOrders — If an adjustment spans items that are partially pre-fulfillment, in-fulfillment, and post-fulfillment, the platform creates a separate ChangeOrder for each segment. Code that assumes a single ChangeOrder per adjustment call will miss records.
  5. CPQ Orders do not create OrderSummary records — CPQ uses its own Order object but the OMS trigger that creates OrderSummary only fires for Orders provisioned through the Commerce/OMS activation path. A CPQ Order activated in the standard Salesforce UI will not produce an OrderSummary. Do not mix these paths.

Output Artifacts

ArtifactDescription
OrderSummary recordImmutable-lifecycle-type record representing the commercial truth of the order; anchor for all OMS financial and fulfillment records
FulfillmentOrder + FulfillmentOrderLineItemRouting unit sent to a specific fulfillment location; transitions through Draft → Activated → Fulfilled
ChangeOrderAudit record created by submit-cancel, submit-return, or adjust-item-submit; up to 3 per adjust-item-submit call
ReturnOrder + ReturnOrderLineItemReturn authorization and line-level return records created by submit-return
Platform event subscriptionsFlow or Apex triggers on FOStatusChangedEvent, OrderSumStatusChangedEvent, OrderSummaryCreatedEvent, ProcessExceptionEvent

Official Sources Used

Package files