SfSkills Domains Docs GitHub

Home / architect / order-management-architecture

order-management-architecture

Use when designing or reviewing a Salesforce Order Management (OMS) solution architecture: fulfillment workflow strategy, split-order routing design, Omnichannel Inventory (OCI) integration, returns process architecture, and multi-location inventory management decisions.

Open the skill folder on GitHub

Order Management Architecture

Use this skill when you are designing or reviewing the architecture of a Salesforce Order Management (OMS) implementation: how fulfillment workflows are structured, how split-order routing is configured, how Omnichannel Inventory (OCI) connects as the inventory truth layer, and how returns and refund flows are decoupled. The focus is holistic architecture — how routing variants, inventory signals, and the returns lifecycle interact as a system rather than how individual records are created.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

OMS Object Chain and Routing Unit

The canonical OMS object chain determines where routing decisions are made:

Order (Activated)
  └── OrderSummary
        ├── OrderItemSummary (one per OrderItem)
        └── OrderDeliveryGroupSummary (groups items by shipping address/method)
              └── FulfillmentOrder  ← routing assigns each ODGS to a location
                    └── FulfillmentOrderLineItem
ReturnOrder
  └── ReturnOrderLineItem

Each OrderDeliveryGroupSummary (ODGS) is the unit of fulfillment routing. The routing engine assigns each ODGS to one FulfillmentOrder per fulfillment location. A single customer order with one delivery group fulfilled from one location produces one FulfillmentOrder. A split order with one delivery group fulfilled from two locations produces two FulfillmentOrders for that group. Architects must design routing logic at the ODGS level, not at the order level.

Split-Order Routing and the "Fewest Splits" Algorithm

OMS includes the Find Routes with Fewest Splits Flow action, which implements an iterative minimization algorithm:

  1. First pass: test every single fulfillment location to find locations that can fulfill the entire ODGS without splitting.
  2. Second pass: if no single location can fulfill everything, test pairs of locations to find the combination that minimizes the number of shipments.
  3. The algorithm continues expanding the search until a valid routing set is found or no routing is possible.

This algorithm is a Flow action — it does not execute automatically. Architects must wire it into an orchestrating Flow or Apex process that is triggered by OrderSummary creation or by a manual routing request. If the wiring is absent, OMS does not route; it simply creates unassigned FulfillmentOrders.

Omnichannel Inventory as the Inventory Truth Layer

Omnichannel Inventory (OCI) is a separate provisioned capability that exposes real-time inventory availability across locations via API. OMS routing consults OCI availability data when selecting which fulfillment location(s) can satisfy an ODGS. Key architectural properties:

Returns Architecture and Refund Decoupling

The OMS returns lifecycle is deliberately decoupled into two independent stages:

  1. Return initiation: The submit-return Connect API action creates ReturnOrder and ReturnOrderLineItem records. This marks items as pending return and updates OrderItemSummary quantities but does not issue a refund.
  2. Refund issuance: The ensure-refunds job is a separate asynchronous payment job that runs only after the ReturnOrder has been explicitly progressed (e.g., to a Received or Closed status). The refund job does not fire automatically at return creation.

This decoupling is intentional — it allows warehouse teams to confirm physical receipt of returned goods before money moves. Architects who wire refund logic to fire immediately on return creation break the intended control flow and risk issuing refunds for goods that were never returned. The architecture must include a clear state machine for ReturnOrder status transitions and the trigger conditions for ensure-refunds invocation.

Common Patterns

OCI-Wired Fewest-Splits Routing

When to use: Any B2C or B2B org with two or more fulfillment locations and a requirement to minimize shipment splits (cost control, customer experience, or carrier SLA reasons).

How it works:

  1. An OrderSummary Creation Flow or Platform Event subscriber triggers routing when a new OrderSummary reaches Created status.
  2. The Flow calls Find Routes with Fewest Splits, passing the ODGS ID and an OCI availability query result for the relevant SKUs at each candidate location.
  3. The action returns a ranked set of location assignments. The Flow creates FulfillmentOrders from the winning assignment.
  4. If OCI reservation succeeds for all items, the FulfillmentOrders advance to Allocated. If reservation fails for any item, the Flow rolls back FulfillmentOrder creation and re-queues for retry.

Why not the alternative: Routing without the fewest-splits action defaults to first-available logic, which creates unnecessary split orders — increasing shipping cost and customer confusion. Routing without OCI wiring means the "fewest splits" calculation has no real inventory data and will assign locations that cannot actually fulfill.

Returns State Machine with Deferred Refund

When to use: Any OMS implementation with customer returns, regardless of whether returns are self-service (storefront) or agent-initiated (Service Cloud).

How it works:

  1. submit-return Connect API action creates ReturnOrder with status Draft or Submitted.
  2. A warehouse process (manual or via Flows on ReturnOrder status) transitions the ReturnOrder through In Transit → Received when goods arrive.
  3. A quality check step (optional) transitions to Closed.
  4. The ensure-refunds job is invoked only after the ReturnOrder reaches Closed (or whatever status the org defines as "refund eligible").
  5. The refund job calls the payment gateway asynchronously. Results post back via Payment Gateway Log records.

Why not the alternative: Triggering ensure-refunds at return creation (step 1) issues refunds before goods are received. If the customer never returns the item, the merchant has already refunded. The deferred pattern also separates the customer-facing return confirmation email from the financial settlement, allowing different teams to own each step.

Decision Guidance

SituationRecommended ApproachReason
B2B-only org with Order ManagementConnected Commerce Order RoutingB2B-specific routing features; Growth routing adds B2C overhead not needed
B2C or mixed B2B+B2C orgGrowth Order RoutingOnly variant that supports B2C order routing natively
2+ fulfillment locations with split-order requirementOCI + Fewest Splits Flow actionOCI provides inventory signal; without it, fewest-splits has no data
OCI not provisioned, routing requiredSingle-location routing with manual overrideDo not attempt multi-location routing without OCI; design for OCI as a future phase
Returns where refund timing is criticalDeferred ensure-refunds tied to ReturnOrder status transitionPrevents premature refund issuance; keeps financial and warehouse workflows separate
High-volume returns (1000+/day)Batch invocation of ensure-refundsSynchronous refund invocation at this volume will hit callout and CPU governor limits
Inventory reservation failuresRetry queue via Platform EventOCI is eventually consistent; reservation failures are expected under load

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

  1. Confirm routing variant and OCI provisioning — Before designing anything, establish which routing variant is licensed (Connected Commerce or Growth) and whether OCI is provisioned. Document these as fixed constraints. Do not design a multi-location routing architecture without confirmed OCI provisioning.
  2. Map the fulfillment location topology — List all fulfillment locations (warehouses, stores, 3PLs), their OCI location IDs, and the SKU populations each can fulfill. This topology is the input to the fewest-splits algorithm configuration and determines the search space for routing decisions.
  3. Design the routing trigger and orchestration Flow — Define what event triggers routing (OrderSummary creation, manual agent action, or status change). Build the orchestrating Flow that calls Find Routes with Fewest Splits, handles OCI reservation results, and creates FulfillmentOrders from the winning assignment. Include a retry path for OCI reservation failures.
  4. Design the returns state machine — Document the full ReturnOrder status lifecycle: what statuses exist, what transitions are allowed, which team owns each transition (storefront, warehouse, finance), and at which status the ensure-refunds job is invoked. Ensure the state machine is implemented as a Flow or Apex trigger on ReturnOrder — not as ad-hoc manual updates.
  5. Validate governor limit profiles — Estimate the governor limit consumption for the routing transaction profile (OCI query + Flow invocation + FulfillmentOrder creation) at peak order volume. Confirm the profile stays within 50% of limits. For batch returns processing, estimate the ensure-refunds callout volume and verify it stays within the 100-callout-per-transaction limit.
  6. Review against Well-Architected pillars — Walk the architecture through Reliability (what happens when OCI is slow or down?), Performance (routing latency at peak volume), and Adaptability (can new fulfillment locations be added without re-architecting the routing Flow?).
  7. Produce deliverables — Generate the OMS architecture decision record, routing flow diagram, returns state machine diagram, and OCI integration topology. Validate all deliverables against the review checklist before sign-off.

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. OCI not provisioned = single-location fallback with no warning — If OCI is not provisioned, the Find Routes with Fewest Splits Flow action has no inventory signal. It does not error; it silently routes all orders to the single configured default location. Architects who assume the routing Flow will "just work" without OCI will not see failures during testing (single-location orgs work fine) and will discover the gap in production when multi-location routing produces wrong assignments.
  2. OCI availability is eventually consistent — reservation failures are expected — OCI availability queries return counts that may be seconds to low minutes stale under concurrent order load. Two orders for the same SKU can both see "5 in stock" simultaneously, but only one reservation will succeed. The architecture must treat reservation failure as a normal code path requiring retry or fallback, not as an error condition.
  3. Refund job does not fire until ReturnOrder is explicitly progressed — The ensure-refunds job is decoupled from return creation by design. Calling submit-return does NOT trigger a refund. The refund job must be explicitly invoked after the ReturnOrder reaches the correct status. Orgs that do not implement the ReturnOrder status transition workflow will have returns stuck in Submitted with no refund ever issued.
  4. FulfillmentOrder creation is not automatic — OMS does not create FulfillmentOrders on its own. An orchestrating Flow or Apex process must be built and wired to the OrderSummary creation event. If this wiring is absent, OrderSummary records will be created but no FulfillmentOrders will ever be generated and orders will never fulfill.
  5. OrderDeliveryGroupSummary is the routing unit, not the Order — Architects who design routing logic at the Order level miss that a single Order can have multiple delivery groups (e.g., ship-to-home and pick-up-in-store items in the same order). Each ODGS routes independently. Routing logic that operates on the Order as a whole will produce incorrect FulfillmentOrder assignments for multi-delivery-group orders.

Output Artifacts

ArtifactDescription
OMS Architecture Decision RecordDocuments routing variant selection, OCI integration approach, returns decoupling strategy, and key tradeoffs
Fulfillment Location TopologyTable of fulfillment locations, OCI location IDs, SKU populations, and routing priority weights
Routing Flow DesignDiagram of the orchestrating Flow: trigger event, OCI query, fewest-splits action, FulfillmentOrder creation, and failure retry path
Returns State MachineState diagram of ReturnOrder status lifecycle with team ownership per transition and ensure-refunds trigger point
Governor Limit AnalysisTransaction profiles for routing and returns batch processing with limit consumption estimates at peak volume

Dependencies

Package files