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.

3.8 KB
Raw Blame
---
title: "Order group service methods"
sidebarTitle: "Service"
description: "Seller module service methods for OrderGroup records, the filters they accept, and how they compute totals."
---

Order group records live in the Seller module, so you read and write them through the Seller module service. Use it in subscribers, scheduled jobs, and custom steps when you need group rows without child orders. For child orders and their statuses, use the [read workflows](/platform/order-group/reference/workflows) instead.

## Resolve the service

Resolve the Seller module from the Medusa container with `MercurModules.SELLER`. There is no `ORDER_GROUP` module key.

```ts
import { MercurModules } from "@mercurjs/types"

const sellerModuleService = container.resolve(MercurModules.SELLER)

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

The call returns the customer’s 20 newest groups and the total number of groups that match.

## Read methods

The Seller module overrides the generated read methods for `OrderGroup`. All three run one SQL query through `OrderGroupRepository`, which fills `seller_count` and `total`:

| Method | Returns |
| --- | --- |
| `listOrderGroups(filters?, config?, sharedContext?)` | `Promise<OrderGroupDTO[]>` |
| `listAndCountOrderGroups(filters?, config?, sharedContext?)` | `Promise<[OrderGroupDTO[], number]>` |
| `retrieveOrderGroup(id, config?, sharedContext?)` | `Promise<OrderGroupDTO>` |

From `config`, the repository reads `take`, `skip`, and `order` only. It ignores `select` and `relations` and always returns every column plus the two computed fields.

<Warning>
  `retrieveOrderGroup` doesn’t throw when no group has the id: it resolves to `undefined`. Check the value before you use it, or use `getOrderGroupDetailWorkflow`, which throws `NOT_FOUND`.
</Warning>

## Write methods

The write methods are the ones `MedusaService` generates for the model:

| Method | Description |
| --- | --- |
| `createOrderGroups(data)` | Creates one group from a `CreateOrderGroupDTO`, or several from an array |
| `updateOrderGroups(data)` | Updates groups from `UpdateOrderGroupDTO` objects |
| `deleteOrderGroups(ids)` | Deletes groups by id |
| `softDeleteOrderGroups(ids)` | Sets `deleted_at` on groups |
| `restoreOrderGroups(ids)` | Clears `deleted_at` on groups |

Creating a group doesn’t create orders or links. Checkout does that in `completeCartWithSplitOrdersWorkflow`, so prefer the workflow over calling `createOrderGroups` yourself.

## Filters and sorting

The repository builds its own SQL and reads only the top-level keys below. It ignores every other key, including `$and` and `$or`.

| Filter | Matches |
| --- | --- |
| `id` | Group id, as a string or an array |
| `customer_id` | Customer id, as a string or an array |
| `cart_id` | Cart id, as a string or an array |
| `seller_id` | Groups with at least one child order from the seller |
| `status` | Groups with at least one child order in the status |
| `payment_status` | Groups with at least one child order in the derived payment status |
| `sales_channel_id` | Groups with at least one child order in the sales channel |
| `created_at`, `updated_at` | A date or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$like`, `$ilike` |
| `q` | Group id or customer id containing the text, or a display id such as `#G98`, `G98`, or `98` on the group or a child order |

The order-level filters only choose which groups match. `seller_count` and `total` still cover every order in each matching group. Pass `id` as a plain string or array: an `{ $in: [...] }` map isn’t read.

`config.order` sorts by `display_id`, `created_at`, or `updated_at`, with `ASC` or `DESC`. Other keys are ignored. Without a valid key, groups come back by `created_at` descending.