Retrieve an order group with its child orders

Load one order group from server code when you build an order page, an email, or an export that needs the whole purchase.

Before you begin

You need the following:

A completed multi-seller cart: at least one order group in your database, for example from a storefront checkout
The group id: an id with the og prefix, such as og_01JD8Q1234567

Load the group in an API route

Create the route

Run getOrderGroupDetailWorkflow with the group id and the fields you want back.

src/api/admin/purchases/[id]/route.ts

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { result: order_group } = await getOrderGroupDetailWorkflow(
    req.scope
  ).run({
    input: {
      order_group_id: req.params.id,
      fields: ["id", "display_id", "total", "seller_count", "cart_id"],
    },
  })

  res.json({ order_group })
}

The workflow adds the child order fields it needs on top of yours, so order_group.orders is always populated. Each order carries payment_status and fulfillment_status.

Add the child order fields you display

Ask for extra order fields with the orders. prefix.

const fields = [
  "id",
  "display_id",
  "total",
  "orders.display_id",
  "orders.total",
  "orders.seller.name",
]

The workflow always returns orders.id, orders.status, orders.currency_code, and orders.items.*. Everything else on the order comes from your list.

Handle a missing group

The workflow throws a NOT_FOUND error when no group has the id. Inside an API route, Medusa’s error handler turns it into a 404 response, so you don’t need to check the result.

Keep payment collections and fulfillments in the response

The workflow loads every child order’s payment collections and fulfillments to compute the statuses, then drops them from the result. To keep them, include a field that contains payment_collections or fulfillments:

fields: [
  "id",
  "orders.payment_collections.id",
  "orders.fulfillments.id",
]

Before the payment is captured, payment_collections holds the cart’s shared collection. After capture, it holds the order’s own collection. Fields that start with orders.cart keep the child orders’ cart in the result too.

Follow the cart link

Expand the read-only cart link to get the basket the group came from:

fields: ["id", "cart.id", "cart.email", "cart.completed_at"]

The cart is completed and frozen, so these values match what the shopper paid for.

Find the group for an order

When you start from a child order id, look up the group through the order_group_order link entity, then run the workflow with its id:

const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

const { data: [link] } = await query.graph({
  entity: "order_group_order",
  fields: ["order_group_id"],
  filters: { order_id: "order_01JD8Q1234568" },
})

ContainerRegistrationKeys comes from @medusajs/framework/utils. link is undefined when the order isn’t part of a group.

Use the workflow rather than retrieveOrderGroup when you need child orders. The service method returns the group row and its computed totals only, without orders or statuses.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Retrieve an order group with its child orders

Before you begin

Load the group in an API route

Keep payment collections and fulfillments in the response

Follow the cart link

Find the group for an order

Next steps

​Before you begin

​Load the group in an API route

​Keep payment collections and fulfillments in the response

​Follow the cart link

​Find the group for an order

​Next steps

Before you begin

Load the group in an API route

Keep payment collections and fulfillments in the response

Follow the cart link

Find the group for an order

Next steps