Skip to main content
Three workflows and one step make up the order group surface: the checkout split that creates groups, and two read workflows that return groups with derived child order statuses. Import them from @mercurjs/core/workflows and run them with the Medusa container.

​
completeCartWithSplitOrdersWorkflow

Completes a cart by creating one order per seller under a new order group. Workflow id complete-cart-with-split-orders. Mercur’s cart completion route and processPaymentWorkflow both run it. It returns { order_group_id: string }. If a group with the same cart_id already exists, the workflow skips the split and returns that group’s id. The workflow stores its execution (store: true) and keeps it for 3 days. It holds a lock on the cart id with a 30-second wait timeout and a 2-minute time to live, so concurrent completions of one cart run one at a time.

​
Hooks

SetOrderStatusHookResult is exported with the workflow. status_by_seller_id is keyed by seller id and takes precedence over status.

​
Steps

The workflow runs these steps in order. Steps 3 to 6 run only when the cart has no order_cart link yet, so a cart counts as completed once its orders are linked to it:
  1. acquireLockStep on the cart id, then queries for the cart’s order_cart links, an existing group, and the cart.
  2. validateCartItemsStep, validateCartPaymentsStep and compensatePaymentIfNeededStep, then the validate and setOrderStatus hooks.
  3. validateSellerCartItemsStep and validateSellerCartShippingStep.
  4. createOrderGroupStep, then createOrdersStep.
  5. createRemoteLinkStep, mirrorLineItemOfferLinksToOrderStep, updateCartsStep to set completed_at, reserveInventoryStep, registerUsageStep, and two emitEventStep calls.
  6. authorizePaymentSessionStep, then splitCapturedCartPaymentWorkflow and refreshOrderCommissionLinesWorkflow as steps.
  7. releaseLockStep on the cart id.

​
Events

​
getOrderGroupDetailWorkflow

Retrieves one order group with its child orders and sets payment_status and fulfillment_status on each order. Workflow id get-order-group-detail. Its input type is GetOrderGroupDetailWorkflowInput. It returns the group. The workflow always adds id, orders.id, orders.status, orders.version, orders.currency_code, and orders.items.* to your fields, plus the payment collection and fulfillment fields it needs for the statuses. It throws NOT_FOUND when no group has the id. The workflow removes some data it loaded for itself before it returns:
  • orders.payment_collections: kept only when a requested field contains payment_collections
  • orders.fulfillments: kept only when a requested field contains fulfillments
  • orders.cart: kept only when a requested field starts with orders.cart

​
getOrderGroupsListWorkflow

Lists order groups with their child orders and derived statuses. Workflow id get-order-groups-list. Its input type is GetOrderGroupsListWorkflowInput. It returns { rows, metadata }, where metadata holds count, skip, and take. It adds the same child order fields as the detail workflow and removes the same data, and adds orders.seller.id when you pass sellerId. sellerId trims orders but doesn’t filter groups. Pass variables.seller_id as well to return only groups where the seller has an order. The filter keys are listed in Filters and sorting.

​
createOrderGroupStep

Creates one OrderGroup record, or returns the cart’s existing group when there is one. Step id create-order-group. It returns the group. On rollback, it deletes the group with deleteOrderGroups only if the step created it. Use it in your own workflow only when you also create and link the child orders yourself.