Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

5.3 KB
Raw Blame
---
title: "Order group workflows"
sidebarTitle: "Workflows"
description: "Input, output, hooks, steps, and events of the checkout split and the order group read workflows."
---

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.

```ts
import {
  completeCartWithSplitOrdersWorkflow,
  createOrderGroupStep,
  getOrderGroupDetailWorkflow,
  getOrderGroupsListWorkflow,
} from "@mercurjs/core/workflows"
```

## 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.

| Input | Type | Description |
| --- | --- | --- |
| `cart_id` | `string` | The cart to complete |

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

| Hook | Receives | Use it to |
| --- | --- | --- |
| `validate` | `{ input, cart }` | Throw to stop the checkout before anything is created |
| `setOrderStatus` | `{ cart }` | Return `{ status?, status_by_seller_id? }` to set each child order’s initial status; the default is `pending` |

`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

| Event | Payload |
| --- | --- |
| `order.placed` | `{ id }`, once per child order |
| `order_group.created` | `{ id }` of the new group |

## 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`.

| Input | Type | Description |
| --- | --- | --- |
| `order_group_id` | `string` | The group to retrieve |
| `fields` | `string[]` | Fields to return, in `query.graph` syntax |

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`.

| Input | Type | Description |
| --- | --- | --- |
| `fields` | `string[]` | Fields to return, in `query.graph` syntax |
| `variables` | `object`, optional | Filters plus `skip`, `take`, and `order` |
| `sellerId` | `string \| string[]`, optional | Removes other sellers’ orders from each returned group |

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](/platform/order-group/reference/service#filters-and-sorting).

## createOrderGroupStep

Creates one `OrderGroup` record, or returns the cart's existing group when there is one. Step id `create-order-group`.

| Input | Type | Description |
| --- | --- | --- |
| `cart_id` | `string` | The completed cart |
| `customer_id` | `string \| null`, optional | The customer on the cart |

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.