@mercurjs/docs 2.2.0-canary.40

package/content/references/api/admin/commission-rates/retrieve-commission-rate.mdx

@@ -0,0 +1,70 @@
+---
+title: "Retrieve Commission Rate"
+api: "GET /admin/commission-rates/{id}"
+description: "Retrieve a commission rate by ID."
+---
+
+Returns a single commission rate with its rules and per-currency values.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The commission rate's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">Comma-separated fields to include in the response.</ParamField>
+
+## Response
+
+<ResponseField name="commission_rate" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The commission rate's ID.</ResponseField>
+    <ResponseField name="name" type="string">The rate's display name.</ResponseField>
+    <ResponseField name="code" type="string">The rate's unique code.</ResponseField>
+    <ResponseField name="type" type="string">The rate type: `fixed` or `percentage`.</ResponseField>
+    <ResponseField name="value" type="number">The commission value.</ResponseField>
+    <ResponseField name="currency_code" type="string | null">Currency of a fixed rate's value.</ResponseField>
+    <ResponseField name="include_tax" type="boolean">Whether commission is calculated on tax-inclusive amounts.</ResponseField>
+    <ResponseField name="include_shipping" type="boolean">Whether shipping is included in the commission base.</ResponseField>
+    <ResponseField name="is_enabled" type="boolean">Whether the rate is active.</ResponseField>
+    <ResponseField name="is_default" type="boolean">Whether this is the marketplace default rate.</ResponseField>
+    <ResponseField name="rules" type="object[]">Rules scoping the rate, each with `id`, `reference`, and `reference_id`.</ResponseField>
+    <ResponseField name="values" type="object[]">Per-currency fixed amounts, each with `id`, `currency_code`, and `amount`.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/commission-rates/comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { commission_rate } = await client.admin.commissionRates.$id.query({
+  $id: "comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "commission_rate": {
+    "id": "comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+    "name": "Default",
+    "code": "default",
+    "type": "percentage",
+    "value": 10,
+    "currency_code": null,
+    "include_tax": false,
+    "include_shipping": false,
+    "is_enabled": true,
+    "is_default": true,
+    "rules": [],
+    "values": []
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/commission-rates/update-commission-rate.mdx

@@ -0,0 +1,84 @@
+---
+title: "Update Commission Rate"
+api: "POST /admin/commission-rates/{id}"
+description: "Update a commission rate."
+---
+
+Updates a commission rate's properties.
+
+<Note>
+  Rules are managed separately through the
+  [batch rules endpoint](/rc/references/api/admin/commission-rates/batch-commission-rules).
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The commission rate's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="name" type="string">The rate's display name.</ParamField>
+<ParamField body="code" type="string">Unique code identifying the rate.</ParamField>
+<ParamField body="type" type="string">The rate type: `fixed` or `percentage`.</ParamField>
+<ParamField body="value" type="number">The commission value — a percentage or a fixed amount.</ParamField>
+<ParamField body="currency_code" type="string">Currency of a fixed rate's value.</ParamField>
+<ParamField body="include_tax" type="boolean">Whether commission is calculated on tax-inclusive amounts.</ParamField>
+<ParamField body="include_shipping" type="boolean">Whether shipping is included in the commission base.</ParamField>
+<ParamField body="is_enabled" type="boolean">Whether the rate is active.</ParamField>
+<ParamField body="values" type="object[]">
+  Per-currency fixed amounts.
+  <Expandable title="properties">
+    <ParamField body="currency_code" type="string" required>The value's currency code.</ParamField>
+    <ParamField body="amount" type="number" required>The fixed commission amount for that currency.</ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField name="commission_rate" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The commission rate's ID.</ResponseField>
+    <ResponseField name="name" type="string">The rate's display name.</ResponseField>
+    <ResponseField name="code" type="string">The rate's unique code.</ResponseField>
+    <ResponseField name="type" type="string">The rate type: `fixed` or `percentage`.</ResponseField>
+    <ResponseField name="value" type="number">The commission value.</ResponseField>
+    <ResponseField name="is_enabled" type="boolean">Whether the rate is active.</ResponseField>
+    <ResponseField name="rules" type="object[]">Rules scoping the rate.</ResponseField>
+    <ResponseField name="values" type="object[]">Per-currency fixed amounts.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/commission-rates/comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"value": 15, "is_enabled": true}'
+```
+
+```ts JS Client
+const { commission_rate } = await client.admin.commissionRates.$id.mutate({
+  $id: "comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+  value: 15,
+  is_enabled: true,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "commission_rate": {
+    "id": "comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+    "name": "Default",
+    "code": "default",
+    "type": "percentage",
+    "value": 15,
+    "is_enabled": true,
+    "is_default": true,
+    "rules": [],
+    "values": []
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/members/list-members.mdx

@@ -0,0 +1,61 @@
+---
+title: "List Members"
+api: "GET /admin/members"
+description: "Retrieve a paginated list of members across all sellers."
+---
+
+Returns member records platform-wide, useful for finding a member to add to a seller's team.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="10">Maximum number of records to return.</ParamField>
+<ParamField query="offset" type="number" default="0">Number of records to skip.</ParamField>
+<ParamField query="order" type="string">Field to sort by, prefix with `-` for descending order.</ParamField>
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</ParamField>
+<ParamField query="q" type="string">Search term matched against member fields.</ParamField>
+<ParamField query="email" type="string">Filter by member email.</ParamField>
+
+## Response
+
+<ResponseField name="members" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The member's ID.</ResponseField>
+    <ResponseField name="email" type="string">The member's email address.</ResponseField>
+    <ResponseField name="is_active" type="boolean">Whether the member's account is active.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+<ResponseField name="count" type="number">Total number of matching members.</ResponseField>
+<ResponseField name="offset" type="number">Number of records skipped.</ResponseField>
+<ResponseField name="limit" type="number">Number of records returned.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/members?email=owner@acme.co' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { members, count } = await client.admin.members.query({
+  email: "owner@acme.co",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "members": [
+    {
+      "id": "mem_01HXYZMEMAA",
+      "email": "owner@acme.co",
+      "is_active": true,
+      "created_at": "2026-06-01T10:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 10
+}
+```
+</ResponseExample>

package/content/references/api/admin/offers/batch-create-offers.mdx

@@ -0,0 +1,130 @@
+---
+title: "Batch Create Offers"
+api: "POST /admin/offers/batch"
+description: "Create up to 100 offers for a seller in one request."
+---
+
+Creates multiple offers on behalf of a seller. The authenticated admin user is recorded as the creator.
+
+## Body parameters
+
+<ParamField body="seller_id" type="string" required>ID of the seller the offers belong to.</ParamField>
+<ParamField body="offers" type="object[]" required>
+  The offers to create — between 1 and 100.
+  <Expandable title="properties">
+    <ParamField body="sku" type="string" required>The offer's SKU.</ParamField>
+    <ParamField body="variant_id" type="string" required>ID of the product variant to offer.</ParamField>
+    <ParamField body="shipping_profile_id" type="string" required>ID of the seller's shipping profile.</ParamField>
+    <ParamField body="prices" type="object[]" required>
+      Offer prices — at least one.
+      <Expandable title="properties">
+        <ParamField body="amount" type="number" required>The price amount.</ParamField>
+        <ParamField body="currency_code" type="string" required>The price currency.</ParamField>
+        <ParamField body="min_quantity" type="number">Minimum quantity the price applies to.</ParamField>
+        <ParamField body="max_quantity" type="number">Maximum quantity the price applies to.</ParamField>
+        <ParamField body="rules" type="object">Price rules as attribute-value pairs.</ParamField>
+      </Expandable>
+    </ParamField>
+    <ParamField body="inventory_items" type="object[]" required>
+      Inventory items backing the offer — at least one.
+      <Expandable title="properties">
+        <ParamField body="title" type="string">The inventory item's title.</ParamField>
+        <ParamField body="sku" type="string">The inventory item's SKU.</ParamField>
+        <ParamField body="required_quantity" type="number" default="1">Quantity required per unit sold.</ParamField>
+        <ParamField body="stock_levels" type="object[]">
+          Initial stock levels.
+          <Expandable title="properties">
+            <ParamField body="location_id" type="string" required>The stock location's ID.</ParamField>
+            <ParamField body="stocked_quantity" type="number" required>Quantity in stock at the location.</ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    <ParamField body="ean" type="string">The offer's EAN.</ParamField>
+    <ParamField body="upc" type="string">The offer's UPC.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField name="offers" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="seller_id" type="string">ID of the seller who owns the offer.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the offered product variant.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string">ID of the offer's shipping profile.</ResponseField>
+    <ResponseField name="sku" type="string">The offer's SKU.</ResponseField>
+    <ResponseField name="prices" type="object[]">The offer's prices.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">The offer's linked inventory items.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/offers/batch' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "seller_id": "sel_01HXYZ",
+    "offers": [
+      {
+        "sku": "SHIRT-M-BLUE",
+        "variant_id": "variant_01HXYZ",
+        "shipping_profile_id": "sp_01HXYZ",
+        "prices": [{ "amount": 2500, "currency_code": "usd" }],
+        "inventory_items": [
+          {
+            "sku": "SHIRT-M-BLUE",
+            "required_quantity": 1,
+            "stock_levels": [{ "location_id": "sloc_01HXYZ", "stocked_quantity": 100 }]
+          }
+        ]
+      }
+    ]
+  }'
+```
+
+```ts JS Client
+const { offers } = await client.admin.offers.batch.mutate({
+  seller_id: "sel_01HXYZ",
+  offers: [
+    {
+      sku: "SHIRT-M-BLUE",
+      variant_id: "variant_01HXYZ",
+      shipping_profile_id: "sp_01HXYZ",
+      prices: [{ amount: 2500, currency_code: "usd" }],
+      inventory_items: [
+        {
+          sku: "SHIRT-M-BLUE",
+          required_quantity: 1,
+          stock_levels: [{ location_id: "sloc_01HXYZ", stocked_quantity: 100 }],
+        },
+      ],
+    },
+  ],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201
+{
+  "offers": [
+    {
+      "id": "offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+      "seller_id": "sel_01HXYZ",
+      "variant_id": "variant_01HXYZ",
+      "shipping_profile_id": "sp_01HXYZ",
+      "sku": "SHIRT-M-BLUE",
+      "prices": [
+        { "id": "price_01HXYZ", "amount": 2500, "currency_code": "usd" }
+      ],
+      "inventory_items": [
+        { "id": "iitem_01HXYZ", "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1, "sku": "SHIRT-M-BLUE" }
+      ]
+    }
+  ]
+}
+```
+</ResponseExample>

package/content/references/api/admin/offers/delete-offer.mdx

@@ -0,0 +1,40 @@
+---
+title: "Delete Offer"
+api: "DELETE /admin/offers/{id}"
+description: "Delete an offer."
+---
+
+Deletes an offer by ID.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The offer's ID.</ParamField>
+
+## Response
+
+<ResponseField name="id" type="string">The deleted offer's ID.</ResponseField>
+<ResponseField name="object" type="string">The object type: `offer`.</ResponseField>
+<ResponseField name="deleted" type="boolean">Whether the offer was deleted.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X DELETE 'http://localhost:9000/admin/offers/offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const result = await client.admin.offers.$id.delete({
+  $id: "offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "id": "offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+  "object": "offer",
+  "deleted": true
+}
+```
+</ResponseExample>

package/content/references/api/admin/offers/list-offers.mdx

@@ -0,0 +1,106 @@
+---
+title: "List Offers"
+api: "GET /admin/offers"
+description: "Retrieve a paginated list of offers across all sellers."
+---
+
+Returns offers with their seller, variant, shipping profile, prices, and inventory items.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">Maximum number of records to return.</ParamField>
+<ParamField query="offset" type="number" default="0">Number of records to skip.</ParamField>
+<ParamField query="order" type="string">Field to sort by, prefix with `-` for descending order.</ParamField>
+<ParamField query="fields" type="string">Comma-separated fields to include in the response.</ParamField>
+<ParamField query="q" type="string">Search term matched against offers.</ParamField>
+<ParamField query="id" type="string | string[]">Filter by offer ID(s).</ParamField>
+<ParamField query="seller_id" type="string | string[]">Filter by seller ID(s).</ParamField>
+<ParamField query="variant_id" type="string | string[]">Filter by product variant ID(s).</ParamField>
+<ParamField query="shipping_profile_id" type="string | string[]">Filter by shipping profile ID(s).</ParamField>
+<ParamField query="sku" type="string | string[]">Filter by SKU(s).</ParamField>
+<ParamField query="ean" type="string | string[]">Filter by EAN(s).</ParamField>
+<ParamField query="upc" type="string | string[]">Filter by UPC(s).</ParamField>
+<ParamField query="group_by_seller" type="boolean">Group results by seller.</ParamField>
+<ParamField query="status" type="string | string[]">Filter by the offered product's status.</ParamField>
+<ParamField query="category_id" type="string | string[]">Filter by product category ID(s).</ParamField>
+<ParamField query="collection_id" type="string | string[]">Filter by product collection ID(s).</ParamField>
+<ParamField query="type_id" type="string | string[]">Filter by product type ID(s).</ParamField>
+<ParamField query="tag_id" type="string | string[]">Filter by product tag ID(s).</ParamField>
+<ParamField query="created_at" type="object">Filter by creation date using operators like `$gte` and `$lte`.</ParamField>
+<ParamField query="updated_at" type="object">Filter by update date using operators like `$gte` and `$lte`.</ParamField>
+
+## Response
+
+<ResponseField name="offers" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="seller_id" type="string">ID of the seller who owns the offer.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the offered product variant.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the offered product.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string">ID of the offer's shipping profile.</ResponseField>
+    <ResponseField name="sku" type="string">The offer's SKU.</ResponseField>
+    <ResponseField name="ean" type="string | null">The offer's EAN.</ResponseField>
+    <ResponseField name="upc" type="string | null">The offer's UPC.</ResponseField>
+    <ResponseField name="created_by" type="string">ID of the actor who created the offer.</ResponseField>
+    <ResponseField name="variant_count" type="number">Number of variants on the offered product.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="seller" type="object">The seller, with `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="product_variant" type="object">The variant, with `id`, `title`, and `sku`.</ResponseField>
+    <ResponseField name="shipping_profile" type="object">The shipping profile, with `id` and `name`.</ResponseField>
+    <ResponseField name="prices" type="object[]">Offer prices, each with `id`, `amount`, `currency_code`, `min_quantity`, `max_quantity`, and `price_rules`.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">Linked inventory items, each with `id`, `inventory_item_id`, `required_quantity`, and `sku`.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+<ResponseField name="count" type="number">Total number of matching offers.</ResponseField>
+<ResponseField name="offset" type="number">Number of records skipped.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of records returned.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/offers?seller_id=sel_01HXYZ&limit=20' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { offers, count } = await client.admin.offers.query({
+  seller_id: "sel_01HXYZ",
+  limit: 20,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "offers": [
+    {
+      "id": "offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+      "seller_id": "sel_01HXYZ",
+      "variant_id": "variant_01HXYZ",
+      "product_id": "prod_01HXYZ",
+      "shipping_profile_id": "sp_01HXYZ",
+      "sku": "SHIRT-M-BLUE",
+      "ean": null,
+      "upc": null,
+      "created_by": "user_01HXYZ",
+      "variant_count": 3,
+      "metadata": null,
+      "seller": { "id": "sel_01HXYZ", "name": "Acme Store", "handle": "acme-store" },
+      "product_variant": { "id": "variant_01HXYZ", "title": "M / Blue", "sku": "SHIRT-M-BLUE" },
+      "shipping_profile": { "id": "sp_01HXYZ", "name": "Default" },
+      "prices": [
+        { "id": "price_01HXYZ", "amount": 2500, "currency_code": "usd", "min_quantity": null, "max_quantity": null }
+      ],
+      "inventory_items": [
+        { "id": "iitem_01HXYZ", "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1, "sku": "SHIRT-M-BLUE" }
+      ]
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>

package/content/references/api/admin/offers/retrieve-offer.mdx

@@ -0,0 +1,82 @@
+---
+title: "Retrieve Offer"
+api: "GET /admin/offers/{id}"
+description: "Retrieve an offer by ID."
+---
+
+Returns a single offer with its seller, variant, shipping profile, prices, and inventory items.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The offer's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">Comma-separated fields to include in the response.</ParamField>
+
+## Response
+
+<ResponseField name="offer" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="seller_id" type="string">ID of the seller who owns the offer.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the offered product variant.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the offered product.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string">ID of the offer's shipping profile.</ResponseField>
+    <ResponseField name="sku" type="string">The offer's SKU.</ResponseField>
+    <ResponseField name="ean" type="string | null">The offer's EAN.</ResponseField>
+    <ResponseField name="upc" type="string | null">The offer's UPC.</ResponseField>
+    <ResponseField name="created_by" type="string">ID of the actor who created the offer.</ResponseField>
+    <ResponseField name="variant_count" type="number">Number of variants on the offered product.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="seller" type="object">The seller, with `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="product_variant" type="object">The variant, with `id`, `title`, and `sku`.</ResponseField>
+    <ResponseField name="shipping_profile" type="object">The shipping profile, with `id` and `name`.</ResponseField>
+    <ResponseField name="prices" type="object[]">Offer prices, each with `id`, `amount`, `currency_code`, `min_quantity`, `max_quantity`, and `price_rules`.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">Linked inventory items, each with `id`, `inventory_item_id`, `required_quantity`, and `sku`.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/offers/offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { offer } = await client.admin.offers.$id.query({
+  $id: "offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "offer": {
+    "id": "offer_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+    "seller_id": "sel_01HXYZ",
+    "variant_id": "variant_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "shipping_profile_id": "sp_01HXYZ",
+    "sku": "SHIRT-M-BLUE",
+    "ean": null,
+    "upc": null,
+    "created_by": "user_01HXYZ",
+    "variant_count": 3,
+    "metadata": null,
+    "seller": { "id": "sel_01HXYZ", "name": "Acme Store", "handle": "acme-store" },
+    "product_variant": { "id": "variant_01HXYZ", "title": "M / Blue", "sku": "SHIRT-M-BLUE" },
+    "shipping_profile": { "id": "sp_01HXYZ", "name": "Default" },
+    "prices": [
+      { "id": "price_01HXYZ", "amount": 2500, "currency_code": "usd", "min_quantity": null, "max_quantity": null }
+    ],
+    "inventory_items": [
+      { "id": "iitem_01HXYZ", "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1, "sku": "SHIRT-M-BLUE" }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/order-groups/list-order-groups.mdx

@@ -0,0 +1,77 @@
+---
+title: "List Order Groups"
+api: "GET /admin/order-groups"
+description: "Retrieve a paginated list of order groups."
+---
+
+Returns order groups — the customer-facing wrappers around per-seller orders created from a multi-seller cart.
+
+<Note>
+  Filtering by `seller_id` narrows results to order groups that contain at
+  least one order belonging to that seller.
+</Note>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">Maximum number of records to return.</ParamField>
+<ParamField query="offset" type="number" default="0">Number of records to skip.</ParamField>
+<ParamField query="order" type="string">Field to sort by, prefix with `-` for descending order.</ParamField>
+<ParamField query="fields" type="string">Comma-separated fields to include in the response.</ParamField>
+<ParamField query="q" type="string">Search term matched against order groups.</ParamField>
+<ParamField query="id" type="string | string[]">Filter by order group ID(s).</ParamField>
+<ParamField query="customer_id" type="string | string[]">Filter by customer ID(s).</ParamField>
+<ParamField query="seller_id" type="string | string[]">Filter to groups containing orders from the given seller(s).</ParamField>
+<ParamField query="status" type="string | string[]">Filter by order group status.</ParamField>
+<ParamField query="sales_channel_id" type="string | string[]">Filter by sales channel ID(s).</ParamField>
+<ParamField query="created_at" type="object">Filter by creation date using operators like `$gte` and `$lte`.</ParamField>
+<ParamField query="updated_at" type="object">Filter by update date using operators like `$gte` and `$lte`.</ParamField>
+
+## Response
+
+<ResponseField name="order_groups" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The order group's ID.</ResponseField>
+    <ResponseField name="customer_id" type="string">ID of the customer who placed the order.</ResponseField>
+    <ResponseField name="seller_count" type="number">Number of sellers in the group.</ResponseField>
+    <ResponseField name="total" type="number">The group's total amount.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+<ResponseField name="count" type="number">Total number of matching order groups.</ResponseField>
+<ResponseField name="offset" type="number">Number of records skipped.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of records returned.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/order-groups?customer_id=cus_01HXYZ&limit=20' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { order_groups, count } = await client.admin.orderGroups.query({
+  customer_id: "cus_01HXYZ",
+  limit: 20,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "order_groups": [
+    {
+      "id": "og_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+      "customer_id": "cus_01HXYZ",
+      "seller_count": 2,
+      "total": 7400,
+      "created_at": "2026-06-01T10:00:00.000Z",
+      "updated_at": "2026-06-01T10:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>