List and filter order groups

List order groups from server code when you build an order history, a report, or a seller-facing view of purchases.

List groups in an API route

Run the list workflow

Pass the fields you want and put filters and pagination in variables.

src/api/admin/purchases/route.ts

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

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await getOrderGroupsListWorkflow(req.scope).run({
    input: {
      fields: ["id", "display_id", "total", "seller_count"],
      variables: { skip: 0, take: 20, order: { display_id: "DESC" } },
    },
  })

  res.json({
    order_groups: result.rows,
    count: result.metadata?.count ?? 0,
  })
}

The workflow returns { rows, metadata }. metadata carries count, skip, and take for pagination. Every row includes its child orders with payment_status and fulfillment_status.

Add filters

Put filter keys next to the pagination keys in variables:

variables: {
  customer_id: "cus_01JD8Q1234567",
  payment_status: ["captured", "partially_captured"],
  created_at: { $gte: "2026-10-01T00:00:00Z" },
  take: 20,
}

This returns the customer’s groups from October 2026 that have at least one captured or partially captured child order.

Filters you can use

The Seller module reads groups through a custom repository that understands a fixed set of top-level keys:

Group filters: id, customer_id, cart_id, as a string or an array
Order filters: seller_id, status, payment_status, sales_channel_id, which match a group when at least one child order matches
Dates: created_at and updated_at, with $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $like, $ilike
Search: q, which matches the group id or customer id, and a display id such as #G98, G98, or 98 on the group or a child order

You can sort by display_id, created_at, or updated_at. Without an order, groups come back newest first.

The repository ignores keys it doesn’t know, including $and and $or. Pass id as a plain string or array, not { $in: [...] }. If you need two id constraints, intersect them yourself before you call the workflow.

Scope groups to one seller

To show a seller only their part of each purchase, filter the groups and trim their orders:

const sellerId = "sel_01JD8Q1234567"

const { result } = await getOrderGroupsListWorkflow(req.scope).run({
  input: {
    fields: ["id", "display_id", "orders.total"],
    variables: { seller_id: sellerId, take: 20 },
    sellerId,
  },
})

The two inputs do different jobs. variables.seller_id keeps only the groups where the seller has an order. sellerId removes the other sellers’ orders from each returned group. sellerId also accepts an array of seller ids.

seller_count and total still describe the whole group when you scope it. Sum the trimmed orders to get the seller’s share.

List groups without child orders

When you only need group rows, call the Seller module service. It skips the child order expansion and the status work:

const sellerModuleService = req.scope.resolve(MercurModules.SELLER)

const [groups, count] = await sellerModuleService.listAndCountOrderGroups(
  { customer_id: "cus_01JD8Q1234567" },
  { take: 20, order: { created_at: "DESC" } }
)

MercurModules comes from @mercurjs/types. The rows still include the computed seller_count and total.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

List groups in an API route

Filters you can use

Scope groups to one seller

List groups without child orders

Next steps

​List groups in an API route

​Filters you can use

​Scope groups to one seller

​List groups without child orders

​Next steps

List groups in an API route

Filters you can use

Scope groups to one seller

List groups without child orders

Next steps