@mercurjs/docs 2.2.0-canary.40

package/content/migration/from-1-x-to-2-0.mdx

@@ -0,0 +1,152 @@
+---
+title: From 1.x to 2.0
+description: What changed and how to port your existing Mercur 1.x code to 2.0.
+---
+
+# Migrating from 1.x to 2.0
+
+Start with a working 2.0 project (see [Installation](/rc/learn/installation)). This guide covers what to change when porting your 1.x code.
+
+<Note>
+**Using version older than 1.4.0?** Your admin panel code is inside the backend repo (not a separate app). When scanning for custom admin code to port, look there instead of `apps/admin/`. Everything else in this guide applies identically.
+</Note>
+
+## Package Mapping
+
+| 1.x Package | 2.0 Equivalent |
+|-------------|----------------|
+| `@mercurjs/b2c-core` | `@mercurjs/core` |
+| `@mercurjs/commission` | Built into core |
+| `@mercurjs/algolia` | Block: `mercurjs add algolia` |
+| `@mercurjs/resend` | No 2.0 equivalent — port manually |
+| `@mercurjs/payment-stripe-connect` | No 2.0 equivalent — port manually |
+| `@mercurjs/stripe-tax-provider` | No 2.0 equivalent — port manually |
+| `@medusajs/admin-vite-plugin` | `@mercurjs/dashboard-sdk` |
+| `@medusajs/js-sdk` | `@mercurjs/client` |
+
+## Directory Mapping
+
+| 1.x | 2.0 |
+|-----|-----|
+| `apps/backend/src/*` | `packages/api/src/*` |
+| `apps/admin/src/routes/` | `apps/admin/src/pages/` |
+| `apps/vendor/src/routes/` | `apps/vendor/src/pages/` |
+
+## What You DON'T Need to Port
+
+Built into core today:
+
+- `seller`
+- `payout`
+- `commission`
+
+Moved to registry blocks:
+
+- `reviews`
+- `requests`
+- `wishlist`
+- `team-management`
+- `algolia`
+- `vendor-notifications`
+- `vendor-chat`
+- `product-import-export`
+
+Install these blocks instead of porting their 1.x package code.
+
+## Current Migration Exceptions
+
+These areas do not currently have full 1.x parity and should be treated as manual migration work:
+
+- **`TaxCode`** — no 2.0 equivalent today. Port the old logic manually if your project depends on it.
+- **`SecondaryCategory`** — no full 1.x parity today. Port manually for now if your project depends on it. Fuller support is planned for a future 2.x release.
+- **Product attributes** — the 1.x attribute module is not carried over 1:1. Port manually for now if your project depends on it. Fuller support is planned for a future 2.x release.
+
+## Order Set to Order Group
+
+The 1.x `OrderSet` entity has been renamed to **`OrderGroup`** in 2.0. This is a breaking change that affects database tables, API endpoints, workflow names, event names, and types.
+
+### What changed
+
+| Aspect | 1.x | 2.0 |
+|--------|-----|-----|
+| Entity / table | `order_set` | `order_group` |
+| ID prefix | `os_` | `og_` |
+| API endpoints | `/admin/order-sets`, `/store/order-set` | `/admin/order-groups`, `/store/order-groups` |
+| Workflows | `getFormattedOrderSetListWorkflow` | `getOrderGroupsListWorkflow`, `getOrderGroupDetailWorkflow` |
+| Events | `OrderSetWorkflowEvents` | `OrderGroupWorkflowEvents` |
+| Types | `OrderSetDTO` | `OrderGroupDTO` (from `@mercurjs/types`) |
+
+### Removed fields
+
+Two fields that existed on `OrderSet` in 1.x have been **removed** from `OrderGroup`:
+
+- **`payment_collection_id`** — Payment collections are now linked at the individual **order** level, not at the group level. Each per-seller order gets its own link to the cart's payment collection during checkout. To get the payment collection, query the linked orders instead of the group.
+- **`sales_channel_id`** — Sales channel information is stored on each individual order, not on the group.
+
+### New computed fields
+
+Two fields are now **computed at query time** (not stored as columns):
+
+- **`seller_count`** — Count of distinct sellers across all linked orders
+- **`total`** — Sum of order totals from linked order summaries
+
+### Migration steps
+
+1. Update imports: `OrderSetDTO` → `OrderGroupDTO` (from `@mercurjs/types`)
+2. Update API calls: `/order-sets` → `/order-groups`
+3. Update workflow references: `getFormattedOrderSetListWorkflow` → `getOrderGroupsListWorkflow`
+4. Update event listeners: `OrderSetWorkflowEvents` → `OrderGroupWorkflowEvents`
+5. If you used `payment_collection_id` or `sales_channel_id` from the order set, retrieve these from the individual orders instead (via the `order_group_order` link)
+
+See [Order Groups](/rc/learn/order-groups) for the full 2.0 data model and API reference.
+
+## Porting Custom Backend Code
+
+### Modules
+
+Copy to `packages/api/src/modules/`, register in `medusa-config.ts`. Update imports from `@mercurjs/b2c-core` to `@mercurjs/core`.
+
+### Workflows
+
+Copy to `packages/api/src/workflows/<entity>/`. Don't create barrel `index.ts` files — conflicts with block installation.
+
+### API Routes
+
+Copy to `packages/api/src/api/`. Type both generics — codegen reads these:
+
+```typescript
+export const GET = async (
+  req: AuthenticatedMedusaRequest<BodyType>,
+  res: MedusaResponse<ResponseType>
+) => { ... }
+```
+
+Run `bunx @mercurjs/cli@rc codegen` after adding routes.
+
+### Links and Subscribers
+
+Copy to `packages/api/src/links/` and `src/subscribers/`. Don't duplicate links that core already provides (seller↔product, seller↔order, etc.).
+
+### Custom Providers
+
+Copy to `packages/api/src/providers/`. Two required changes:
+
+```typescript
+// medusa-config.ts — must use ./src/ prefix
+resolve: './src/providers/my-provider'
+
+// provider index.ts — must import from framework/utils
+import { Modules, ModuleProvider } from "@medusajs/framework/utils"
+```
+
+## Porting Custom Dashboard Code
+
+Only if you have custom pages not covered by core-admin/vendor.
+
+| Old import | New import |
+|-----------|------------|
+| `@medusajs/js-sdk` | `@mercurjs/client` |
+| `@custom-types/*` | `@mercurjs/types` |
+| `@hooks/*`, `@components/*`, `@lib/*` | Keep local, or `@mercurjs/dashboard-shared` if the symbol exists there |
+
+Move pages from `src/routes/` to `src/pages/` with `export default`.

package/content/migration/from-2-0-to-2-1.mdx

@@ -0,0 +1,105 @@
+---
+title: From 2.0 to 2.1
+description: What changed in Mercur 2.1 and how to upgrade an existing 2.0.x project.
+---
+
+# Migrating from 2.0 to 2.1
+
+Mercur `2.1.1` is the first stable release of the 2.x line after `2.0.2`. The only required change is a package rename. Everything else is handled by `bun run medusa db:migrate`.
+
+If you are starting fresh, follow [Installation](/rc/learn/installation) instead — new projects already use the 2.1 names.
+
+## Breaking change: `@mercurjs/core-plugin` → `@mercurjs/core`
+
+The Medusa plugin previously published as `@mercurjs/core-plugin` is now published as **`@mercurjs/core`**. The package contents are the same; only the name changed.
+
+This affects:
+
+- `package.json` — installed package name
+- `medusa-config.ts` — every `resolve: "@mercurjs/core-plugin/..."` value
+- Any source imports in `packages/api/src/**`
+
+### Step 1 — swap the dependency
+
+```bash
+bun remove @mercurjs/core-plugin
+bun add @mercurjs/core@2.1.1
+```
+
+If you use npm/yarn/pnpm, use the equivalent commands for your package manager.
+
+Or edit `packages/api/package.json` by hand — replace the `@mercurjs/core-plugin` entry under `dependencies` with `@mercurjs/core` at the matching version, then run your installer:
+
+```jsonc
+// before
+"dependencies": {
+  "@mercurjs/core-plugin": "2.0.2"
+}
+
+// after
+"dependencies": {
+  "@mercurjs/core": "2.1.1"
+}
+```
+
+```bash
+bun install
+```
+
+### Step 2 — replace strings in config and source
+
+In `packages/api/medusa-config.ts` and anywhere under `packages/api/src/**`, replace every occurrence of `@mercurjs/core-plugin` with `@mercurjs/core`. A repo-wide find-and-replace is safe — there are no other valid uses of the old name.
+
+```ts
+// before
+{
+  resolve: "@mercurjs/core-plugin/modules/seller",
+}
+
+// after
+{
+  resolve: "@mercurjs/core/modules/seller",
+}
+```
+
+```ts
+// before
+import { createSellerWorkflow } from "@mercurjs/core-plugin/workflows"
+
+// after
+import { createSellerWorkflow } from "@mercurjs/core/workflows"
+```
+
+The same applies to:
+
+- `@mercurjs/core-plugin/modules/<module>`
+- `@mercurjs/core-plugin/workflows`
+- `@mercurjs/core-plugin/links`
+- `@mercurjs/core-plugin/api`
+
+### Step 3 — reinstall and rebuild
+
+```bash
+bun install
+bun run build
+```
+
+If TypeScript still complains about `@mercurjs/core-plugin`, you missed an import. Re-run the find-and-replace.
+
+### Step 4 — refresh installed blocks
+
+If your project installed registry blocks (`mercurjs add reviews`, `mercurjs add requests`, etc.) on a 2.0.x version, the local copies still reference `@mercurjs/core-plugin`. Either:
+
+- Run the same find-and-replace inside `packages/api/src/` (registry blocks live there once installed)
+
+## Database migrations
+
+Mercur 2.1 ships several new migrations on the `seller` module. All are non-destructive. Run:
+
+```bash
+bun run medusa db:migrate
+```
+
+## Full changelog
+
+The complete 2.1 changelog is published with the [GitHub release](https://github.com/mercurjs/mercur/releases/tag/v2.1.1).

package/content/migration/overview.mdx

@@ -0,0 +1,58 @@
+---
+title: Migration Overview
+description: Understand what changes between Mercur 1.x and 2.0 and how to migrate your project.
+---
+
+# Migration Overview
+
+Mercur 2.0 replaces the monolithic plugin architecture (`@mercurjs/b2c-core`) with a block-based model (`@mercurjs/core` + registry blocks).
+
+This guide is about **porting your existing 1.x code to a 2.0 project**. For setting up a fresh 2.0 project, see [Installation](/rc/learn/installation).
+
+<Tip>
+If you're using an AI Agent/IDE (Claude Code, Cursor, or similar), your project includes a `migration-guide` skill that can analyze your 1.x Mercur project and walk you through the migration step by step.
+</Tip>
+
+## What Replaced What
+
+| 1.x | 2.0 |
+|-------|--------|
+| `@mercurjs/b2c-core` (monolithic) | `@mercurjs/core` — all core modules built in |
+| `@mercurjs/commission` (separate) | Built into core |
+| `@mercurjs/algolia`, reviews, requests | Registry blocks (`mercurjs add ...`) |
+| `@medusajs/admin-vite-plugin` | `@mercurjs/dashboard-sdk` (virtual modules) |
+| `@medusajs/js-sdk` (manual hooks) | `@mercurjs/client` (generated typed client) |
+| Custom admin/vendor pages | `@mercurjs/admin` / `@mercurjs/vendor` — complete panels out of the box |
+| `apps/backend/` | `packages/api/` |
+| `src/routes/` (admin) | `src/pages/` (file-based routing) |
+| Yarn + Turbo | bun (recommended) |
+
+## What Didn't Change
+
+- MedusaJS v2 foundation (modules, workflows, links, subscribers, API routes)
+- Data model patterns (MikroORM, service layer)
+- Environment variables (`DATABASE_URL`, CORS, secrets — all the same)
+
+## What You Need to Migrate
+
+**Most users don't need to migrate much.** Core-plugin and the official registry blocks cover most standard marketplace functionality. Core-admin/vendor panels provide 34+ pages out of the box.
+
+You only need to port:
+- **Custom modules** — business-specific modules not covered by core or blocks
+- **Custom workflows and routes** — your own endpoints and business logic
+- **Custom dashboard pages** — only if you have domain-specific pages not in core-admin/vendor
+
+<Warning>
+Current migration exceptions:
+
+- `TaxCode` does not have a 2.0 equivalent today and requires manual migration.
+- `SecondaryCategory` does not yet have full 1.x parity and may require manual migration for now.
+- The 1.x product attribute system is not carried over 1:1, so product attributes may require manual migration for now.
+
+See [From 1.x to 2.0](/migrations/from-1-x-to-2-0) for the full migration guidance and current status.
+</Warning>
+
+## Next Steps
+
+- [From 2.0 to 2.1](/migrations/from-2-0-to-2-1) — package rename (`@mercurjs/core-plugin` → `@mercurjs/core`) and a `db:migrate` step
+- [From 1.x to 2.0](/migrations/from-1-x-to-2-0) — full guide for porting an existing 1.x project

package/content/references/api/admin/commission-rates/batch-commission-rules.mdx

@@ -0,0 +1,70 @@
+---
+title: "Batch Commission Rules"
+api: "POST /admin/commission-rates/{id}/rules"
+description: "Create, update, and delete a commission rate's rules in one request."
+---
+
+Applies a batch of rule operations against a commission rate.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The commission rate's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="create" type="object[]">
+  Rules to create.
+  <Expandable title="properties">
+    <ParamField body="reference" type="string" required>The rule target type: `product`, `product_type`, `product_collection`, `product_category`, or `seller`.</ParamField>
+    <ParamField body="reference_id" type="string" required>ID of the referenced entity.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="update" type="object[]">
+  Rules to update.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>The rule's ID.</ParamField>
+    <ParamField body="reference" type="string">The rule target type: `product`, `product_type`, `product_collection`, `product_category`, or `seller`.</ParamField>
+    <ParamField body="reference_id" type="string">ID of the referenced entity.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="delete" type="string[]">IDs of rules to delete.</ParamField>
+
+## Response
+
+<ResponseField name="created" type="object[]">The created rules.</ResponseField>
+<ResponseField name="updated" type="object[]">The updated rules.</ResponseField>
+<ResponseField name="deleted" type="string[]">IDs of the deleted rules.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/commission-rates/comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y/rules' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"create": [{"reference": "seller", "reference_id": "sel_01HXYZ"}], "delete": ["comrule_01HABC"]}'
+```
+
+```ts JS Client
+const { created, updated, deleted } =
+  await client.admin.commissionRates.$id.rules.mutate({
+    $id: "comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+    create: [{ reference: "seller", reference_id: "sel_01HXYZ" }],
+    delete: ["comrule_01HABC"],
+  })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "created": [
+    {
+      "id": "comrule_01HXYZ9A1B2C3D4E5F6G7H8J9K",
+      "reference": "seller",
+      "reference_id": "sel_01HXYZ"
+    }
+  ],
+  "updated": [],
+  "deleted": ["comrule_01HABC"]
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,95 @@
+---
+title: "Create Commission Rate"
+api: "POST /admin/commission-rates"
+description: "Create a commission rate."
+---
+
+Creates a commission rate, optionally with scoping rules and per-currency values.
+
+## Body parameters
+
+<ParamField body="name" type="string" required>The rate's display name.</ParamField>
+<ParamField body="code" type="string" required>Unique code identifying the rate.</ParamField>
+<ParamField body="type" type="string" required>The rate type: `fixed` or `percentage`.</ParamField>
+<ParamField body="value" type="number" required>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="is_default" type="boolean">Whether this is the marketplace default rate.</ParamField>
+<ParamField body="rules" type="object[]">
+  Rules scoping which sellers or products the rate applies to.
+  <Expandable title="properties">
+    <ParamField body="reference" type="string" required>The rule target type: `product`, `product_type`, `product_collection`, `product_category`, or `seller`.</ParamField>
+    <ParamField body="reference_id" type="string" required>ID of the referenced entity.</ParamField>
+  </Expandable>
+</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="is_default" type="boolean">Whether this is the marketplace default rate.</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' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "Electronics", "code": "electronics", "type": "percentage", "value": 12, "rules": [{"reference": "product_category", "reference_id": "pcat_01HXYZ"}]}'
+```
+
+```ts JS Client
+const { commission_rate } = await client.admin.commissionRates.mutate({
+  name: "Electronics",
+  code: "electronics",
+  type: "percentage",
+  value: 12,
+  rules: [{ reference: "product_category", reference_id: "pcat_01HXYZ" }],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201
+{
+  "commission_rate": {
+    "id": "comrate_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
+    "name": "Electronics",
+    "code": "electronics",
+    "type": "percentage",
+    "value": 12,
+    "currency_code": null,
+    "include_tax": false,
+    "include_shipping": false,
+    "is_enabled": true,
+    "is_default": false,
+    "rules": [
+      {
+        "id": "comrule_01HXYZ9A1B2C3D4E5F6G7H8J9K",
+        "reference": "product_category",
+        "reference_id": "pcat_01HXYZ"
+      }
+    ],
+    "values": []
+  }
+}
+```
+</ResponseExample>

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

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

package/content/references/api/admin/commission-rates/list-commission-rates.mdx

@@ -0,0 +1,92 @@
+---
+title: "List Commission Rates"
+api: "GET /admin/commission-rates"
+description: "Retrieve a paginated list of commission rates."
+---
+
+Returns commission rates with their rules and currency-specific values.
+
+<Note>
+  `scope_type` is a virtual filter derived from each rate's rules — it is not a
+  stored column. Use it to filter rates by the scope their rules target.
+</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 commission rates.</ParamField>
+<ParamField query="id" type="string | string[]">Filter by commission rate ID(s).</ParamField>
+<ParamField query="code" type="string | string[]">Filter by commission rate code(s).</ParamField>
+<ParamField query="type" type="string | string[]">Filter by rate type: `fixed` or `percentage`.</ParamField>
+<ParamField query="scope_type" type="string | string[]">Filter by rule scope: `store`, `product_type`, `category`, `store_product_type`, or `store_category`.</ParamField>
+<ParamField query="is_enabled" type="boolean">Filter by enabled state.</ParamField>
+<ParamField query="is_default" type="boolean">Filter by whether the rate is the marketplace default.</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="commission_rates" 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 — a percentage or a fixed amount.</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>
+<ResponseField name="count" type="number">Total number of matching commission rates.</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/commission-rates?scope_type=store&limit=20' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { commission_rates, count } = await client.admin.commissionRates.query({
+  scope_type: "store",
+  limit: 20,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "commission_rates": [
+    {
+      "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": []
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>