Mercur

https://docs.mercurjs.com
Admin
Mercur is an open-source marketplace engine built on Medusa that provides multi-vendor logic, seller...
Tokens:198,274
Snippets:1,799
Trust Score:5.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start the development server

Source: https://docs.mercurjs.com/learn/installation

Commands to navigate to the project directory and start the development server.

```bash
cd <your-project-name>
bun dev
```

--------------------------------

### Install dependencies

Source: https://docs.mercurjs.com/migrations/from-2-0-to-2-1

Run the installation command after updating package references.

```bash
bun install
```

--------------------------------

### Install PostgreSQL via Homebrew

Source: https://docs.mercurjs.com/learn/installation

Alternative method for starting PostgreSQL on macOS.

```bash
brew install postgresql@16 && brew services start postgresql@16
```

--------------------------------

### Install Block from Custom Registry

Source: https://docs.mercurjs.com/learn/registry

Installs a specific block using the configured custom registry.

```bash
bunx @mercurjs/cli@latest add @my-org/reviews
```

--------------------------------

### Add blocks from the registry

Source: https://docs.mercurjs.com/learn/installation

Install specific blocks into the project.

```bash
bunx @mercurjs/cli@latest add <block-name>
```

--------------------------------

### Install Search Providers

Source: https://docs.mercurjs.com/resources/integrations/search

Use the CLI to add Algolia or Meilisearch providers to your project.

```bash
bunx @mercurjs/cli@latest add algolia
# or
bunx @mercurjs/cli@latest add meilisearch
```

--------------------------------

### Install Mercur CLI

Source: https://docs.mercurjs.com/tools/cli

Install the latest version of the Mercur CLI globally using Bun.

```bash
bun add -g @mercurjs/cli@latest
```

--------------------------------

### Install Mercur blocks

Source: https://docs.mercurjs.com/learn/blocks

Use the CLI to fetch and install blocks into your project. The CLI automatically resolves dependencies and maps files based on your project structure.

```bash
bunx @mercurjs/cli@latest add reviews
bunx @mercurjs/cli@latest add wishlist product-import-export
```

--------------------------------

### Retrieve current member response example

Source: https://docs.mercurjs.com/references/api/vendor/members/retrieve-current-member

Example JSON response containing the seller member's profile, role, and seller information.

```json
{
  "seller_member": {
    "id": "selmem_01HXYZ",
    "is_owner": true,
    "member": { "id": "mem_01HXYZ", "first_name": "Jane", "last_name": "Doe", "email": "owner@acme.com" },
    "rbac_role": { "id": "role_seller_administration", "name": "Administration" },
    "seller": { "id": "sel_01HXYZ", "name": "Acme Store", "status": "open" }
  }
}
```

--------------------------------

### Install the product-import-export block

Source: https://docs.mercurjs.com/resources/tutorials/import-export-products

Use the Mercur CLI to add the block files to your project.

```bash
bunx @mercurjs/cli@latest add product-import-export
```

--------------------------------

### Install a block

Source: https://docs.mercurjs.com/resources/tutorials/build-a-block

Command to add a specific block from a registered registry to the consumer project.

```bash
bunx @mercurjs/cli@latest add @my-org/announcements
```

--------------------------------

### List Products Request

Source: https://docs.mercurjs.com/references/api/admin/products/list-products

Examples of how to fetch products using cURL or the JavaScript client.

```bash
curl 'http://localhost:9000/admin/products?status[]=published&limit=20' \
  -H 'Authorization: Bearer <token>'
```

```javascript
const { products, count } = await client.admin.products.query({
  status: ["published"],
  limit: 20,
})
```

--------------------------------

### Run PostgreSQL with Docker

Source: https://docs.mercurjs.com/learn/installation

Quickly start a local PostgreSQL instance using Docker.

```bash
docker run -d --name mercur-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 postgres:16
```

--------------------------------

### List Offers Request

Source: https://docs.mercurjs.com/references/api/store/offers/list-offers

Examples of how to fetch offers using cURL or the JavaScript client.

```bash
curl 'http://localhost:9000/store/offers?product_id=prod_01JB2K5M8N&region_id=reg_01JB2K4S1T&fields=%2Bcalculated_price' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
```

```javascript
const { offers, count } = await client.store.offers.query({
  product_id: "prod_01JB2K5M8N",
  region_id: "reg_01JB2K4S1T",
  fields: "+calculated_price",
})
```

--------------------------------

### Create Product Request

Source: https://docs.mercurjs.com/references/api/admin/products/create-product

Examples for creating a product using cURL and the JS Client.

```bash
curl -X POST 'http://localhost:9000/admin/products' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Linen Shirt",
    "seller_ids": ["sel_01HXYZABCDEF"],
    "options": [{ "title": "Size", "values": ["S", "M"] }],
    "variants": [
      { "title": "S", "sku": "LS-S", "options": { "Size": "S" } },
      { "title": "M", "sku": "LS-M", "options": { "Size": "M" } }
    ],
    "attributes": [{ "title": "Material", "type": "single_select", "values": ["Linen"] }]
  }'
```

```javascript
const { product } = await client.admin.products.mutate({
  title: "Linen Shirt",
  seller_ids: ["sel_01HXYZABCDEF"],
  options: [{ title: "Size", values: ["S", "M"] }],
  variants: [
    { title: "S", sku: "LS-S", options: { Size: "S" } },
    { title: "M", sku: "LS-M", options: { Size: "M" } },
  ],
  attributes: [{ title: "Material", type: "single_select", values: ["Linen"] }],
})
```

--------------------------------

### Retrieve Product Attribute

Source: https://docs.mercurjs.com/references/api/store/product-attributes/retrieve-product-attribute

Use these examples to fetch a specific product attribute by its ID.

```bash
curl 'http://localhost:9000/store/product-attributes/attr_01JB2K7A1B' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
```

```javascript
const { product_attribute } = await client.store.productAttributes.$id.query({
  $id: "attr_01JB2K7A1B",
})
```

--------------------------------

### Confirm Product Request

Source: https://docs.mercurjs.com/references/api/admin/products/confirm-product

Examples for confirming a product using cURL and the JavaScript client.

```bash
curl -X POST 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/confirm' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"internal_note": "Looks good"}'
```

```javascript
const { product } = await client.admin.products.$id.confirm.mutate({
  $id: "prod_01HXYZABCDEF",
  internal_note: "Looks good",
})
```

--------------------------------

### Install and Verify Claude Code MCP

Source: https://docs.mercurjs.com/resources/ai/mcp

Commands to install the Mercur MCP server and verify the installation in Claude Code.

```bash
claude mcp add --transport http mercur https://docs.mercurjs.com/mcp
```

```bash
claude mcp list
```

--------------------------------

### Create payout onboarding

Source: https://docs.mercurjs.com/learn/payouts

Initiates provider onboarding for a seller account. Requires a return URL in the context object.

```bash
curl -X POST http://localhost:9000/vendor/payout-accounts/<account-id>/onboarding \
  -H "Authorization: Bearer <seller-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "return_url": "https://my-store.com/settings/payouts"
    }
  }'
```

--------------------------------

### Install block dependencies

Source: https://docs.mercurjs.com/resources/tutorials/import-export-products

Install required Medusa and multer packages in the API workspace.

```bash
cd packages/api
bun add @medusajs/core-flows multer @types/multer
```

--------------------------------

### Register a store-setup widget

Source: https://docs.mercurjs.com/resources/tutorials/extend-onboarding

Define a widget configuration with the 'seller.setup.before' zone to inject custom components into the onboarding flow.

```typescript
import "@mercurjs/vendor/extension-targets"
import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
import { SellerDTO } from "@mercurjs/types"
import { Container, Heading, Input, Button, Text, toast } from "@medusajs/ui"
import { useMutation } from "@tanstack/react-query"
import { useState } from "react"

import { client } from "../lib/client"

export const config = defineWidgetConfig({
  zone: "seller.setup.before",
})

const TaxIdSetup = ({ data: seller }: { data?: SellerDTO }) => {
  const [taxId, setTaxId] = useState("")

  const { mutate, isPending } = useMutation({
    mutationFn: () =>
      client.vendor.sellers.$id.mutate({
        $id: seller!.id,
        // additional_data is accepted on every vendor seller route —
        // it never touches the built-in seller columns.
        additional_data: { tax_id: taxId },
      }),
    onSuccess: () => toast.success("Tax ID saved"),
    onError: () => toast.error("Could not save Tax ID"),
  })

  if (!seller) {
    return null
  }

  return (
    <Container className="mb-2 flex items-end gap-x-3">
      <div className="flex-1">
        <Heading level="h2">Complete your tax details</Heading>
        <Text size="small" className="text-ui-fg-subtle">
          Add your VAT / Tax ID to finish store setup.
        </Text>
        <Input
          className="mt-3"
          placeholder="VAT-000000"
          value={taxId}
          onChange={(e) => setTaxId(e.target.value)}
          data-testid="tax-id-setup-input"
        />
      </div>
      <Button
        size="small"
        isLoading={isPending}
        disabled={!taxId}
        onClick={() => mutate()}
        data-testid="tax-id-setup-save"
      >
        Save
      </Button>
    </Container>
  )
}

export default TaxIdSetup
```

--------------------------------

### Discover and View Block Details

Source: https://docs.mercurjs.com/resources/tutorials/add-a-block

Search the registry for available blocks and inspect their file structure and dependencies before installation.

```bash
bunx @mercurjs/cli@latest search --query reviews
bunx @mercurjs/cli@latest view reviews
```

--------------------------------

### Add documentation dependency to existing projects

Source: https://docs.mercurjs.com/resources/ai/overview

Install the documentation package to enable local agent access.

```bash
bun add @mercurjs/docs
```

--------------------------------

### Product Attributes Response Example

Source: https://docs.mercurjs.com/references/api/admin/product-attributes/list-product-attributes

Example JSON response structure returned by the product attributes list endpoint.

```json
{
  "product_attributes": [
    {
      "id": "pattr_01HXYZABCDEF",
      "name": "Material",
      "handle": "material",
      "type": "single_select",
      "is_required": false,
      "is_filterable": true,
      "is_variant_axis": false,
      "is_active": true,
      "values": [
        { "id": "pattrval_01HXYZABCDEF", "name": "Linen", "rank": 0 }
      ]
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 20
}
```

--------------------------------

### Onboarding Response Example

Source: https://docs.mercurjs.com/references/api/vendor/payout-accounts/create-onboarding

The successful response returns the onboarding ID, provider-specific data, and context.

```json
{
  "onboarding": {
    "id": "onb_01HXYZ",
    "data": { "url": "https://connect.stripe.com/setup/s/..." },
    "context": { "return_url": "https://vendor.example.com/payouts" },
    "created_at": "2026-01-15T10:00:00.000Z"
  }
}
```

--------------------------------

### Create Onboarding Session via cURL

Source: https://docs.mercurjs.com/references/api/vendor/payout-accounts/create-onboarding

Use this cURL request to initiate an onboarding session by providing the payout account ID and necessary context URLs.

```bash
curl -X POST 'http://localhost:9000/vendor/payout-accounts/pacc_01HXYZ/onboarding' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-seller-id: <seller_id>' \
  -H 'Content-Type: application/json' \
  -d '{"context": {"refresh_url": "https://vendor.example.com/payouts", "return_url": "https://vendor.example.com/payouts"}}'
```

--------------------------------

### GET /vendor/offers

Source: https://docs.mercurjs.com/references/api/vendor

List offers.

```APIDOC
## GET /vendor/offers

### Description
List offers.

### Method
GET

### Endpoint
/vendor/offers
```

--------------------------------

### Initiate Seller Onboarding

Source: https://docs.mercurjs.com/resources/tutorials/seller-payouts-stripe

Use this request to create a payout account and generate a Stripe onboarding link for the seller.

```bash
curl -X POST http://localhost:9000/vendor/payout-accounts/<account-id>/onboarding \
  -H "Authorization: Bearer <seller-token>" \
  -H "Content-Type: application/json" \
  -d '{ "context": { "return_url": "http://localhost:7001/settings/payouts" } }'
```

--------------------------------

### GET /vendor/fulfillment-providers

Source: https://docs.mercurjs.com/references/api/vendor

List fulfillment providers.

```APIDOC
## GET /vendor/fulfillment-providers

### Description
List fulfillment providers.

### Method
GET

### Endpoint
/vendor/fulfillment-providers
```

--------------------------------

### GET /vendor/products/:id

Source: https://docs.mercurjs.com/references/api/vendor

Retrieve a product.

```APIDOC
## GET /vendor/products/:id

### Description
Retrieve a product.

### Method
GET

### Endpoint
/vendor/products/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The product ID
```

--------------------------------

### Retrieve a Product via API

Source: https://docs.mercurjs.com/references/api/store/products/retrieve-product

Examples of how to fetch a product using cURL or the JavaScript client.

```bash
curl 'http://localhost:9000/store/products/prod_01JB2K5M8N?region_id=reg_01JB2K4S1T&fields=*variants.calculated_price' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
```

```javascript
const { product } = await client.store.products.$id.query({
  $id: "prod_01JB2K5M8N",
  region_id: "reg_01JB2K4S1T",
  fields: "*variants.calculated_price",
})
```

--------------------------------

### GET /vendor/payouts[/:id]

Source: https://docs.mercurjs.com/references/api/vendor

Retrieve payout history.

```APIDOC
## GET /vendor/payouts[/:id]

### Description
Retrieve payout history.

### Method
GET

### Endpoint
/vendor/payouts[/:id]
```

--------------------------------

### GET /vendor/orders

Source: https://docs.mercurjs.com/references/api/vendor

List the seller’s orders.

```APIDOC
## GET /vendor/orders

### Description
List the seller’s orders.

### Method
GET

### Endpoint
/vendor/orders
```

--------------------------------

### GET /vendor/product-variants

Source: https://docs.mercurjs.com/references/api/vendor

List variants across products.

```APIDOC
## GET /vendor/product-variants

### Description
List variants across products.

### Method
GET

### Endpoint
/vendor/product-variants
```

--------------------------------

### Configure AI agent instructions

Source: https://docs.mercurjs.com/resources/ai/overview

Create an AGENTS.md file to direct agents to read the bundled documentation before making changes.

```markdown
# Mercur: read the docs before coding

Before any non-trivial change, read the bundled documentation — it is
version-matched to this project's installed packages, and far more accurate
than training data.

1. Read the index: `node_modules/@mercurjs/docs/llms.txt`
2. Open the pages it points to under `node_modules/@mercurjs/docs/content/`

Don't guess at an API, data model, or file convention the docs already describe.
```

--------------------------------

### GET /vendor/shipping-option-types[/:id]

Source: https://docs.mercurjs.com/references/api/vendor

List shipping option types.

```APIDOC
## GET /vendor/shipping-option-types[/:id]

### Description
List shipping option types.

### Method
GET

### Endpoint
/vendor/shipping-option-types[/:id]
```

--------------------------------

### Install a Block

Source: https://docs.mercurjs.com/resources/tutorials/add-a-block

Copy the block's source code into the project based on the aliases defined in blocks.json.

```bash
bunx @mercurjs/cli@latest add reviews
```

--------------------------------

### GET /vendor/products/:id/variants/:variant_id

Source: https://docs.mercurjs.com/references/api/vendor

Retrieve a product variant.

```APIDOC
## GET /vendor/products/:id/variants/:variant_id

### Description
Retrieve a product variant.

### Method
GET

### Endpoint
/vendor/products/:id/variants/:variant_id

### Parameters
#### Path Parameters
- **id** (string) - Required - The product ID
- **variant_id** (string) - Required - The variant ID
```

--------------------------------

### GET /vendor/sellers

Source: https://docs.mercurjs.com/references/api/vendor

Lookup registration or create a seller account.

```APIDOC
## GET /vendor/sellers

### Description
Lookup registration or create a seller account. This endpoint is public.

### Method
GET

### Endpoint
/vendor/sellers
```

--------------------------------

### Initialize a new Mercur project

Source: https://docs.mercurjs.com/learn/mirakl-alternative

Use this command to scaffold a new marketplace application using the Mercur CLI.

```sh
bun create mercur-app@latest my-marketplace
```

--------------------------------

### GET /vendor/payouts

Source: https://docs.mercurjs.com/references/api/vendor/payouts/list-payouts

Returns the payouts belonging to the current seller.

```APIDOC
## GET /vendor/payouts

### Description
Returns the payouts belonging to the current seller.

### Method
GET

### Endpoint
/vendor/payouts

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Maximum number of items to return. Default: 20
- **offset** (number) - Optional - Number of items to skip. Default: 0
- **order** (string) - Optional - Field to sort by, prefixed with `-` for descending order.
- **fields** (string) - Optional - Comma-separated fields to include in the response.
- **status** (string | string[]) - Optional - Filter by payout status: `pending`, `processing`, `paid`, `failed`, `canceled`.
- **created_at** (object) - Optional - Filter by creation date using operators like `$gte`, `$lte`, `$gt`, `$lt`.
- **updated_at** (object) - Optional - Filter by update date using operators like `$gte`, `$lte`, `$gt`, `$lt`.

### Request Example
curl 'http://localhost:9000/vendor/payouts?status=paid' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-seller-id: <seller_id>'

### Response
#### Success Response (200)
- **payouts** (object[]) - List of payout objects
- **count** (number) - Total number of payouts
- **offset** (number) - Number of items skipped
- **limit** (number) - Maximum number of items returned

#### Response Example
{
  "payouts": [
    {
      "id": "pout_01HXYZ",
      "display_id": 42,
      "amount": 1250,
      "currency_code": "usd",
      "status": "paid",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 20
}
```

--------------------------------

### Create a new Mercur project

Source: https://docs.mercurjs.com/learn/installation

Initialize a new project using the Mercur CLI.

```bash
bun create mercur-app@latest
```

--------------------------------

### GET /vendor/payouts/{id}

Source: https://docs.mercurjs.com/references/api/vendor/payouts/retrieve-payout

Retrieves a payout by its unique identifier.

```APIDOC
## GET /vendor/payouts/{id}

### Description
Returns a payout, verifying it belongs to the current seller.

### Method
GET

### Endpoint
/vendor/payouts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The payout’s ID.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include in the response.

### Request Example
```bash
curl 'http://localhost:9000/vendor/payouts/pout_01HXYZ' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-seller-id: <seller_id>'
```

### Response
#### Success Response (200)
- **payout** (object) - The payout object.
  - **id** (string) - The payout’s ID.
  - **display_id** (number) - Human-readable payout number.
  - **amount** (number) - The payout amount.
  - **currency_code** (string) - The payout currency.
  - **status** (enum) - One of `pending`, `processing`, `paid`, `failed`, `canceled`.
  - **data** (object) - Provider-specific data.
  - **created_at** (string) - Creation timestamp.
  - **updated_at** (string) - Update timestamp.

#### Response Example
```json
{
  "payout": {
    "id": "pout_01HXYZ",
    "display_id": 42,
    "amount": 1250,
    "currency_code": "usd",
    "status": "paid",
    "created_at": "2026-01-15T10:00:00.000Z"
  }
}
```
```

--------------------------------

### GET /store/product-categories

Source: https://docs.mercurjs.com/references/api/store/product-categories/list-product-categories

Returns a paginated list of product categories.

```APIDOC
## GET /store/product-categories

### Description
Returns a paginated list of product categories; inactive and internal categories are always excluded.

### Method
GET

### Endpoint
/store/product-categories

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Maximum number of categories to return. Default: 50.
- **offset** (number) - Optional - Number of categories to skip before collecting results. Default: 0.
- **order** (string) - Optional - Field to sort by, prefixed with `-` for descending order.
- **fields** (string) - Optional - Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
- **q** (string) - Optional - Free-text search term applied to category fields.
- **id** (string | string[]) - Optional - Filter by one or more category IDs.
- **handle** (string | string[]) - Optional - Filter by one or more category handles.
- **parent_category_id** (string | string[]) - Optional - Filter by parent category ID; pass `null` to fetch top-level categories.
- **include_ancestors_tree** (boolean) - Optional - Include each category’s ancestors in `parent_category`.
- **include_descendants_tree** (boolean) - Optional - Include each category’s descendants in `category_children`.
- **created_at** (object) - Optional - Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
- **updated_at** (object) - Optional - Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
- **$and** (object[]) - Optional - Join multiple filter objects with a logical AND.
- **$or** (object[]) - Optional - Join multiple filter objects with a logical OR.

### Request Example
curl 'http://localhost:9000/store/product-categories?parent_category_id=null&limit=50' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ'

### Response
#### Success Response (200)
- **product_categories** (object[]) - List of product categories.
- **count** (number) - Total number of matching categories.
- **offset** (number) - Number of skipped categories.
- **limit** (number) - Maximum number of returned categories.

#### Response Example
{
  "product_categories": [
    {
      "id": "pcat_01JB2K6A2B",
      "name": "Shirts",
      "description": "",
      "handle": "shirts",
      "rank": 0,
      "parent_category_id": null,
      "parent_category": null,
      "category_children": [{ "id": "pcat_01JB2K6H7J", "name": "Linen Shirts" }],
      "metadata": null,
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-05-01T10:00:00.000Z"
    }
  ],
  "count": 8,
  "offset": 0,
  "limit": 50
}
```

--------------------------------

### POST /vendor/products

Source: https://docs.mercurjs.com/references/api/vendor

Create a product.

```APIDOC
## POST /vendor/products

### Description
Create a product (created as proposed).

### Method
POST

### Endpoint
/vendor/products
```

--------------------------------

### GET /admin/commission-rates

Source: https://docs.mercurjs.com/learn/commissions

Retrieves a list of all configured commission rates.

```APIDOC
## GET /admin/commission-rates

### Description
Retrieves a list of all commission rates defined in the system.

### Method
GET

### Endpoint
/admin/commission-rates
```

--------------------------------

### Response Schema

Source: https://docs.mercurjs.com/references/api/admin/orders/get-order-commission-lines

Example JSON response structure for a successful request.

```json
{
  "commission_lines": [
    {
      "id": "comline_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
      "item_id": "ordli_01HXYZ",
      "shipping_method_id": null,
      "commission_rate_id": "comrate_01HXYZ",
      "code": "default",
      "rate": 10,
      "amount": 490,
      "description": null,
      "created_at": "2026-06-01T10:00:00.000Z",
      "updated_at": "2026-06-01T10:00:00.000Z"
    }
  ],
  "count": 1
}
```

--------------------------------

### GET /vendor/products/:id/preview

Source: https://docs.mercurjs.com/references/api/vendor

Preview a product with pending changes applied.

```APIDOC
## GET /vendor/products/:id/preview

### Description
Preview a product with pending changes applied.

### Method
GET

### Endpoint
/vendor/products/:id/preview

### Parameters
#### Path Parameters
- **id** (string) - Required - The product ID
```

--------------------------------

### Execute createOffersWorkflow

Source: https://docs.mercurjs.com/references/workflows/offer/create-offers

Run the workflow to create new offers with associated inventory and pricing.

```typescript
import { createOffersWorkflow } from "@mercurjs/core/workflows"

const { result } = await createOffersWorkflow(container).run({
  input: {
    offers: [
      {
        seller_id: "sel_123",
        created_by: "member_123",
        variant_id: "variant_123",
        shipping_profile_id: "sp_123",
        sku: "ACME-TEE-M",
        inventory_items: [
          { stock_levels: [{ location_id: "sloc_123", stocked_quantity: 50 }] },
        ],
        prices: [{ amount: 1999, currency_code: "usd" }],
      },
    ],
  },
})
```

--------------------------------

### GET /store/sellers/{id}

Source: https://docs.mercurjs.com/references/api/store/sellers/retrieve-seller

Retrieves the details of a specific seller by their ID.

```APIDOC
## GET /store/sellers/{id}

### Description
Returns a single seller. Sellers that are not `open` or are inside a scheduled closure window return a `404`.

### Method
GET

### Endpoint
/store/sellers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The seller’s ID.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.

### Request Example
```bash
curl 'http://localhost:9000/store/sellers/sel_01JB2K8A1B' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
```

### Response
#### Success Response (200)
- **seller** (object) - The seller object.

#### Response Example
```json
{
  "seller": {
    "id": "sel_01JB2K8A1B",
    "name": "Nordic Textiles",
    "handle": "nordic-textiles",
    "description": "Scandinavian linen and wool.",
    "logo": "https://cdn.example.com/nordic-logo.png",
    "banner": null,
    "is_premium": false,
    "metadata": null
  }
}
```
```

--------------------------------

### Product Response Example

Source: https://docs.mercurjs.com/references/api/vendor/products/retrieve-product

The JSON structure returned upon a successful 200 OK request.

```json
{
  "product": {
    "id": "prod_01HXYZ",
    "title": "Acme T-Shirt",
    "status": "published",
    "handle": "acme-t-shirt",
    "variants": [
      { "id": "variant_01HXYZ", "title": "M", "sku": "ACME-SHIRT-M" }
    ]
  }
}
```

--------------------------------

### GET /vendor/members/me

Source: https://docs.mercurjs.com/references/api/vendor/members/retrieve-current-member

Retrieves the seller member record for the authenticated member.

```APIDOC
## GET /vendor/members/me

### Description
Returns the seller member record for the authenticated member, including the member profile, role, and the seller with its address, payment details, and professional details.

### Method
GET

### Endpoint
/vendor/members/me

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include in the response.

### Request Example
```bash
curl 'http://localhost:9000/vendor/members/me' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-seller-id: <seller_id>'
```

### Response
#### Success Response (200)
- **seller_member** (object) - The seller member record.
  - **id** (string) - The seller member’s ID.
  - **is_owner** (boolean) - Whether the member owns the seller account.
  - **member** (object) - The member’s profile (first name, last name, email, locale).
  - **rbac_role** (object) - The member’s role for this seller.
  - **seller** (object) - The active seller, with address, payment_details, and professional_details.

#### Response Example
```json
{
  "seller_member": {
    "id": "selmem_01HXYZ",
    "is_owner": true,
    "member": { "id": "mem_01HXYZ", "first_name": "Jane", "last_name": "Doe", "email": "owner@acme.com" },
    "rbac_role": { "id": "role_seller_administration", "name": "Administration" },
    "seller": { "id": "sel_01HXYZ", "name": "Acme Store", "status": "open" }
  }
}
```
```

--------------------------------

### Create Onboarding Session via JS Client

Source: https://docs.mercurjs.com/references/api/vendor/payout-accounts/create-onboarding

Use the JS client to mutate the onboarding state for a specific payout account.

```javascript
const { onboarding } = await client.vendor.payoutAccounts.$id.onboarding.mutate({
  $id: "pacc_01HXYZ",
  context: {
    refresh_url: "https://vendor.example.com/payouts",
    return_url: "https://vendor.example.com/payouts",
  },
})
```

--------------------------------

### Display project info

Source: https://docs.mercurjs.com/tools/cli

Show current project configuration and diagnostic information.

```bash
bunx @mercurjs/cli@latest info
```

--------------------------------

### GET /admin/sellers/{id}/products

Source: https://docs.mercurjs.com/references/api/admin/sellers/list-seller-products

Returns the products owned by the seller.

```APIDOC
## GET /admin/sellers/{id}/products

### Description
Returns the products owned by the seller.

### Method
GET

### Endpoint
/admin/sellers/{id}/products

### Parameters
#### Path Parameters
- **id** (string) - Required - The seller’s ID.

#### Query Parameters
- **limit** (number) - Optional - Maximum number of records to return (default: 50).
- **offset** (number) - Optional - Number of records to skip (default: 0).
- **order** (string) - Optional - Field to sort by, prefix with `-` for descending order.
- **fields** (string) - Optional - Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.
- **q** (string) - Optional - Search term matched against product fields.
- **id** (string | string[]) - Optional - Filter by product ID(s).
- **status** (string | string[]) - Optional - Filter by product status.
- **collection_id** (string | string[]) - Optional - Filter by collection ID(s).
- **sales_channel_id** (string | string[]) - Optional - Filter by sales channel ID(s).
- **type_id** (string | string[]) - Optional - Filter by product type ID(s).
- **tag_id** (string | string[]) - Optional - Filter by product tag ID(s).
- **created_at** (object) - Optional - Filter by creation date with operators like `$gte`, `$lte`.
- **updated_at** (object) - Optional - Filter by update date with operators like `$gte`, `$lte`.

### Response
#### Success Response (200)
- **products** (object[]) - List of products.
- **count** (number) - Total number of the seller’s products.
- **offset** (number) - Number of records skipped.
- **limit** (number) - Number of records returned.

### Response Example
{
  "products": [
    {
      "id": "prod_01HXYZPRODAA",
      "title": "Canvas Tote Bag",
      "handle": "canvas-tote-bag",
      "status": "published",
      "thumbnail": "https://cdn.example.com/tote.jpg",
      "collection": null,
      "sales_channels": [],
      "variants": [{ "id": "variant_01HXYZVARAA" }],
      "created_at": "2026-06-03T10:00:00.000Z",
      "updated_at": "2026-06-03T10:00:00.000Z"
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 20
}
```

--------------------------------

### Offer Response Example

Source: https://docs.mercurjs.com/references/api/store/offers/retrieve-offer

The JSON structure returned upon a successful 200 OK request.

```json
{
  "offer": {
    "id": "offer_01JB2K6G5H",
    "seller_id": "sel_01JB2K8A1B",
    "variant_id": "variant_01JB2K6E4F",
    "product_id": "prod_01JB2K5M8N",
    "shipping_profile_id": "sp_01JB2K9C2D",
    "sku": "NT-LINEN-M",
    "ean": null,
    "upc": null,
    "seller": { "id": "sel_01JB2K8A1B", "name": "Nordic Textiles", "handle": "nordic-textiles" },
    "product_variant": { "id": "variant_01JB2K6E4F", "title": "M", "sku": null, "price_set": { "id": "pset_01JB2K9E3F" } },
    "shipping_profile": { "id": "sp_01JB2K9C2D", "name": "Default" },
    "prices": [
      { "id": "price_01JB2K9G4H", "amount": 4500, "currency_code": "eur", "min_quantity": null, "max_quantity": null }
    ],
    "inventory_item_link": [],
    "calculated_price": {
      "calculated_amount": 4500,
      "original_amount": 4500,
      "currency_code": "eur"
    },
    "metadata": null,
    "created_at": "2026-05-01T10:00:00.000Z",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
}
```

--------------------------------

### GET /admin/offers/{id}

Source: https://docs.mercurjs.com/references/api/admin/offers/retrieve-offer

Retrieves the details of a specific offer by its ID.

```APIDOC
## GET /admin/offers/{id}

### Description
Retrieves the details of a specific offer by its ID.

### Method
GET

### Endpoint
/admin/offers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The offer’s ID.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include in the response.

### Response
#### Success Response (200)
- **offer** (object) - The offer object containing details such as id, seller_id, variant_id, product_id, shipping_profile_id, sku, ean, upc, created_by, variant_count, metadata, seller, product_variant, shipping_profile, prices, inventory_items, created_at, and updated_at.

#### Response Example
{
  "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" }
    ]
  }
}
```

--------------------------------

### GET /admin/offers/{id}

Source: https://docs.mercurjs.com/references/api/admin/offers/retrieve-offer

Retrieves a single offer by its unique identifier.

```APIDOC
## GET /admin/offers/{id}

### Description
Returns a single offer with its seller, variant, shipping profile, prices, and inventory items.

### Method
GET

### Endpoint
/admin/offers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the offer.

### Response
#### Success Response (200)
- **offer** (object) - The offer details including seller, product_variant, shipping_profile, prices, and inventory_items.

#### Response Example
{
  "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" }
    ]
  }
}
```

--------------------------------

### Create Product via cURL

Source: https://docs.mercurjs.com/references/api/vendor/products/create-product

Use this cURL command to create a product by sending a POST request with the required authorization and seller ID headers.

```bash
curl -X POST 'http://localhost:9000/vendor/products' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-seller-id: <seller_id>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Acme T-Shirt",
    "options": [{ "title": "Size", "values": ["S", "M"] }],
    "variants": [
      { "title": "S", "sku": "ACME-SHIRT-S", "options": { "Size": "S" } },
      { "title": "M", "sku": "ACME-SHIRT-M", "options": { "Size": "M" } }
    ]
  }'
```

--------------------------------

### GET /admin/payouts/{id}

Source: https://docs.mercurjs.com/references/api/admin/payouts/retrieve-payout

Retrieves a single payout by its unique identifier.

```APIDOC
## GET /admin/payouts/{id}

### Description
Returns a single payout with its payout account and seller details.

### Method
GET

### Endpoint
/admin/payouts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The payout’s ID.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include in the response.

### Response
#### Success Response (200)
- **payout** (object) - The payout object containing id, display_id, amount, currency_code, status, data, account, seller, created_at, and updated_at.

#### Response Example
{
  "payout": {
    "id": "pout_01HXYZ8Q2M4N6P8R0T2V4W6X8Y",
    "display_id": 42,
    "amount": 1250,
    "currency_code": "usd",
    "status": "completed",
    "data": null,
    "account": { "id": "pacc_01HXYZ", "status": "active" },
    "seller": { "id": "sel_01HXYZ", "name": "Acme Store", "handle": "acme-store" }
  }
}
```

--------------------------------

### Reinstall and build project

Source: https://docs.mercurjs.com/migrations/from-2-0-to-2-1

Reinstall dependencies and rebuild the project after applying changes.

```bash
bun install
bun run build
```

--------------------------------

### GET /admin/order-groups/{id}

Source: https://docs.mercurjs.com/references/api/admin/order-groups/retrieve-order-group

Retrieves a single order group by its ID.

```APIDOC
## GET /admin/order-groups/{id}

### Description
Returns a single order group based on the provided ID.

### Method
GET

### Endpoint
/admin/order-groups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The order group’s ID.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include in the response.

### Response
#### Success Response (200)
- **order_group** (object) - The order group details.
  - **id** (string) - The order group’s ID.
  - **customer_id** (string) - ID of the customer who placed the order.
  - **seller_count** (number) - Number of sellers in the group.
  - **total** (number) - The group’s total amount.
  - **created_at** (string) - Creation timestamp.
  - **updated_at** (string) - Last update timestamp.

### Response Example
{
  "order_group": {
    "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"
  }
}
```

--------------------------------

### Set up the global commission via Admin API

Source: https://docs.mercurjs.com/learn/commissions

Configures a default percentage-based commission rate that includes shipping costs.

```bash
curl -X POST http://localhost:9000/admin/commission-rates \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Global Commission",
    "code": "global",
    "type": "percentage",
    "value": 15,
    "is_default": true,
    "include_shipping": true
  }'
```

--------------------------------

### Run database migrations

Source: https://docs.mercurjs.com/resources/best-practices/module-links

Command to synchronize link definitions with the database schema.

```bash
npx medusa db:migrate
```

--------------------------------

### Search Response Example

Source: https://docs.mercurjs.com/references/api/store/search/search

The JSON response structure returned by the search endpoint.

```json
{
  "hits": [
    {
      "id": "offer_01JB2K6G5H",
      "type": "offer",
      "title": "Linen Shirt",
      "handle": "linen-shirt",
      "thumbnail": "https://cdn.example.com/linen-shirt.png",
      "seller_handle": "nordic-textiles",
      "product_id": "prod_01JB2K5M8N",
      "variant_id": "variant_01JB2K6E4F",
      "sku": "NT-LINEN-M",
      "category_ids": ["pcat_01JB2K6A2B"],
      "categories": ["Shirts"],
      "calculated_price": {
        "calculated_amount": 4500,
        "original_amount": 5000,
        "currency_code": "eur"
      }
    }
  ],
  "count": 42,
  "limit": 12,
  "offset": 0,
  "facets": {
    "collections": [],
    "categories": [{ "id": "pcat_01JB2K6A2B", "label": "Shirts", "count": 42 }],
    "attributes": [
      {
        "handle": "material",
        "label": "Material",
        "values": [{ "id": "attrval_01JB2K7C2D", "label": "Linen", "count": 30 }]
      }
    ]
  }
}
```
Tokens:
Raw