npm - @mercurjs/docs - Versions diffs - 2.2.1 → 2.3.0-canary.1 - Mend

@mercurjs/docs 2.2.1 → 2.3.0-canary.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (316) hide show

package/content/learn/installation.mdx DELETED Viewed

@@ -1,117 +0,0 @@
----
-title: "Installation"
-description: "Install Mercur and set up your marketplace project."
----
-## Requirements
-- [Node.js v20+](https://nodejs.org/en/download) (LTS version)
-- [Bun v1.3+](https://bun.sh) (recommended package manager)
-- [Git](https://git-scm.com/downloads)
-- PostgreSQL v14+
-<Tip>
-  The quickest way to get PostgreSQL running locally is with Docker:
-  ```bash
-  docker run -d --name mercur-postgres \
-    -e POSTGRES_PASSWORD=postgres \
-    -p 5432:5432 postgres:16
-  ```
-  Or on macOS with Homebrew:
-  ```bash
-  brew install postgresql@16 && brew services start postgresql@16
-  ```
-</Tip>
-## Create a new project
-```bash
-bun create mercur-app@latest
-```
-The CLI will prompt for a project name and template, then handle everything automatically:
-- downloads the template
-- installs dependencies
-- creates and migrates the database
-- seeds initial data
-- starts the development server and opens the admin setup page in your browser
-### Options
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--template <template>` | Template to use (`basic` or `plugin`) | prompted |
-| `--db-connection-string <string>` | Full PostgreSQL connection string | — |
-| `--db-host <host>` | PostgreSQL host | `localhost` |
-| `--db-port <port>` | PostgreSQL port | `5432` |
-| `--no-deps` | Skip dependency installation | — |
-| `--skip-db` | Skip database setup | — |
-## Access your marketplace
-Once the development server is running, your marketplace is available at:
-| Panel | URL |
-|-------|-----|
-| API | `http://localhost:9000` |
-| Admin Panel | `http://localhost:9000/dashboard` |
-| Vendor Panel | `http://localhost:9000/seller` |
-### Create an admin account
-The CLI automatically opens the admin invite page in your browser after setup. Follow the on-screen instructions to create your first admin account.
-### Create your first seller
-The seed data does not include a seller account. To create one, open the Vendor Panel and register:
-```
-http://localhost:9000/seller/register
-```
-Fill in the registration form and complete the onboarding wizard. Once submitted, the seller will appear in the Admin Panel for approval.
-## Start the development server
-After stopping the server, start it again from your project directory:
-```bash
-cd <your-project-name>
-bun dev
-```
-## Initialize an existing project
-If you have an existing Medusa project, initialize Mercur in it:
-```bash
-bunx @mercurjs/cli@latest init
-```
-This creates a `blocks.json` configuration file in your project.
-## Add blocks
-Install blocks from the registry:
-```bash
-bunx @mercurjs/cli@latest add <block-name>
-```
-Browse available blocks:
-```bash
-bunx @mercurjs/cli@latest search
-```
-## Run database migrations
-After adding blocks that include modules:
-```bash
-bunx medusa db:generate <module1> <module2> ...
-bunx medusa db:migrate
-```

package/content/learn/mirakl-alternative.mdx DELETED Viewed

@@ -1,86 +0,0 @@
----
-title: "Mercur - an open-source Mirakl alternative"
-description: "How Mercur compares to Mirakl and other marketplace platforms: open-source, self-hosted, no GMV fees, full code ownership."
----
-If you're evaluating [Mirakl](https://www.mirakl.com/) - or any hosted, enterprise marketplace SaaS - Mercur is the open-source alternative built for teams that want to own their marketplace outright instead of renting it.
-Mirakl is a mature, capable platform. It's also closed-source, priced as a percentage of the GMV that flows through it, and delivered as a hosted service you don't control. Mercur takes the opposite position: MIT-licensed core, self-hosted on your own infrastructure, no per-transaction cut, and full access to every line of code.
-This page is an honest comparison. Mirakl is the right choice for some teams; Mercur is the right choice for others. The goal here is to help you tell which one you are.
-## At a glance
-|                               | **Mercur**                                                                         | **Mirakl**                              |
-| ----------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------- |
-| **License**                   | Open source (MIT core)                                                             | Proprietary / closed source             |
-| **Hosting**                   | Self-host anywhere, or fully managed (Medusa Cloud / Rigby-hosted)                 | Vendor-hosted SaaS only                 |
-| **Pricing model**             | No GMV fees, no per-transaction cut                                                | Percentage of GMV + platform fees       |
-| **Code ownership**            | Full source access; fork or modify freely                                          | No source access                        |
-| **Customization**             | Extend/override workflows, APIs, and UI without forking                            | Configuration within platform limits    |
-| **Data ownership**            | Your database, your infrastructure                                                 | Vendor-controlled                       |
-| **Tech stack**                | TypeScript, Node.js, React, PostgreSQL                                             | Proprietary                             |
-| **Extensibility**             | Composable blocks, typed API client, workflow hooks, Dashboard SDK                 | Connectors and APIs within the platform |
-| **Storefront**                | Bring your own (headless, API-first)                                               | Integrated / connector-based            |
-| **Enterprise features**       | Mercur Enterprise: Buy Box, dedup, master-data governance, KYC - on your own infra | Included in the platform                |
-| **Support & SLAs**            | Contractual SLAs and named contact via Mercur Enterprise                           | Vendor support contract                 |
-| **Delivery help**             | Rigby builds/launches marketplaces with you                                        | Sales-led onboarding                    |
-| **Time to first marketplace** | `bun create mercur-app` in minutes                                                 | Sales-led onboarding                    |
-## Where Mercur is the better fit
-- **You want to own your marketplace, not rent it.** No percentage of GMV, no per-transaction cut, no vendor lock-in. Your data, customers, and roadmap stay yours.
-- **You have (or want) an engineering team.** Mercur is code you control end-to-end. If you plan to customize deeply - bespoke commission logic, custom vendor onboarding, non-standard order flows - an open, hackable core is a decisive advantage over a configuration-bound SaaS.
-- **You need to control where data lives.** Self-host on your own cloud, on-prem, or inside an air-gapped network. There's no proprietary runtime to adopt and no hosting tier you're forced onto.
-- **You want to avoid platform risk.** MIT license means the core can never be taken away from you, re-priced out from under you, or discontinued.
-## Enterprise-grade, without giving up ownership
-The features that usually pull teams toward Mirakl - a winning-offer engine, product deduplication, master-data governance, multi-channel stock sync, vendor KYC - aren't a reason to accept closed source and GMV fees. **[Mercur Enterprise](https://www.mercurjs.com/enterprise)** delivers that same enterprise surface area as a licensed module suite you deploy and run on your own infrastructure, exactly like the open-source core:
-- **Buy Box / winning-offer engine** - pick the winning offer across competing sellers, the way large marketplaces do.
-- **EAN matching & deduplication** - collapse duplicate seller submissions into a single master product.
-- **Master-data governance** - controlled, auditable catalog data across thousands of vendors.
-- **Multi-channel stock sync** - keep inventory consistent across sales channels and feeds.
-- **Automated split payouts & vendor KYC** - compliant onboarding and settlement at scale.
-…and more, with new modules added over time.
-Everything is maintained, tested, and upgraded by the core team, and backed by a direct support relationship: a dedicated support channel, contractual SLAs with guaranteed response times, prioritized bug fixes and security patches, and hands-on onboarding and architecture guidance. Higher tiers add priority escalation and a named technical contact.
-The difference from Mirakl: you still own the code, host it yourself, and pay no percentage of GMV.
-## Don't want to build it yourself? We'll build it with you
-Mercur is built and maintained by [Rigby](https://rigbyjs.com), a team that has designed, built, and launched multi-vendor marketplaces in production. If you'd rather not staff the whole project, we work alongside your team - architecture reviews, integrating Mercur with your existing stack, hardening, scaling, and getting your marketplace live on schedule.
-This closes the usual "we don't have engineering capacity" gap that sends teams to a fully managed SaaS: you get a done-with-you (or done-for-you) delivery path _and_ keep an open-source core you own. [Talk to our team](https://www.mercurjs.com/contact).
-### Don't want to run the infrastructure either?
-You don't have to. Not wanting to manage servers is not a reason to accept closed source and GMV fees - Mercur runs as a fully managed deployment too. Ship it to [Medusa Cloud](https://medusajs.com/pricing/) with push-to-deploy and auto-scaling, or have Rigby deploy, host, and operate it for you. Either way you get the zero-ops experience of a SaaS while keeping the open-source core, your data, and no percentage of GMV.
-## Migrating from Mirakl
-Already live on Mirakl? Rigby helps you move - porting your catalog, sellers, offers, orders, and commission structure onto Mercur, then hardening and cutting over without disrupting your marketplace. [Talk to our team](https://www.mercurjs.com/contact) to scope a migration.
-## What Mercur gives you
-Built on the [Medusa](https://medusajs.com) commerce framework, Mercur adds the marketplace layer on top:
-- **Multi-vendor sellers** - onboarding, approval, suspension, and member management.
-- **Master products & offers** - a shared catalog where multiple sellers list offers (SKU, price, inventory, shipping) against the same product.
-- **Commissions** - configurable fixed or percentage rules matching across product, type, collection, category, and seller.
-- **Automated vendor payouts** - a pluggable payout pipeline with Stripe Connect out of the box.
-- **Order splitting** - a single customer cart spanning multiple sellers splits into per-seller orders under an order group.
-- **Admin and Vendor panels** - role-specific dashboards, plus a headless Store API for any storefront.
-See [Concepts](/rc/learn/concepts) and [Architecture](/rc/learn/architecture) for the full picture, or jump straight to [Installation](/rc/learn/installation) to spin up a marketplace locally.
-## Get started
-```sh
-bun create mercur-app@latest my-marketplace
-```
-Then head to the [Installation guide](/rc/learn/installation) to run it locally, or [talk to our team](https://www.mercurjs.com/contact) if you're migrating from an existing platform.

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

@@ -1,152 +0,0 @@
----
-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@latest 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 DELETED Viewed

@@ -1,105 +0,0 @@
----
-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 DELETED Viewed

@@ -1,58 +0,0 @@
----
-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/store/search/search.mdx DELETED Viewed

@@ -1,136 +0,0 @@
----
-title: "Search"
-api: "POST /store/search"
-description: "Query the search index across products and offers."
----
-Runs a full-text query against the active search provider's index of products and offers.
-<Note>
-  Customer authentication is optional. When a customer token is provided together with `region_id`, the customer's group memberships enter the pricing context, so hits can carry group-specific `calculated_price` values.
-</Note>
-## Body parameters
-<ParamField body="q" type="string" default="">
-  Search query.
-</ParamField>
-<ParamField body="limit" type="number" default="12">
-  Maximum number of hits to return; minimum `1`, maximum `100`.
-</ParamField>
-<ParamField body="offset" type="number" default="0">
-  Number of hits to skip before collecting results.
-</ParamField>
-<ParamField body="region_id" type="string">
-  Region used to build the pricing context; without it, hits have no `calculated_price`.
-</ParamField>
-<ParamField body="country_code" type="string">
-  Country used for the tax context when the region has automatic taxes.
-</ParamField>
-<ParamField body="province" type="string">
-  Province used for the tax context.
-</ParamField>
-<ParamField body="filters" type="object">
-  Provider-owned filter object passed straight to the active search provider, which defines its shape (for example category, collection, or attribute filters).
-</ParamField>
-## Response
-<ResponseField name="hits" type="object[]">
-  <Expandable title="properties">
-    <ResponseField name="id" type="string">The document's ID.</ResponseField>
-    <ResponseField name="type" type="string">One of `product` or `offer`.</ResponseField>
-    <ResponseField name="title" type="string">Display title.</ResponseField>
-    <ResponseField name="description" type="string">Description text.</ResponseField>
-    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
-    <ResponseField name="thumbnail" type="string">Thumbnail URL.</ResponseField>
-    <ResponseField name="seller_handle" type="string">Handle of the owning seller.</ResponseField>
-    <ResponseField name="collection_id" type="string">ID of the product's collection.</ResponseField>
-    <ResponseField name="collection" type="string">Title of the product's collection.</ResponseField>
-    <ResponseField name="category_ids" type="string[]">IDs of the product's categories.</ResponseField>
-    <ResponseField name="categories" type="string[]">Names of the product's categories.</ResponseField>
-    <ResponseField name="product_id" type="string">Product ID (offer documents).</ResponseField>
-    <ResponseField name="variant_id" type="string">Variant ID (offer documents).</ResponseField>
-    <ResponseField name="sku" type="string">Offer SKU (offer documents).</ResponseField>
-    <ResponseField name="attributes" type="object[]">Filterable attributes with their values.</ResponseField>
-    <ResponseField name="calculated_price" type="object | null">
-      Price for the requested pricing context, with `calculated_amount`, `original_amount`, and `currency_code`.
-    </ResponseField>
-  </Expandable>
-</ResponseField>
-<ResponseField name="count" type="number">Total number of matching documents.</ResponseField>
-<ResponseField name="limit" type="number">The applied limit.</ResponseField>
-<ResponseField name="offset" type="number">The applied offset.</ResponseField>
-<ResponseField name="facets" type="object">
-  <Expandable title="properties">
-    <ResponseField name="collections" type="object[]">Collection facets with `id`, `label`, and `count`.</ResponseField>
-    <ResponseField name="categories" type="object[]">Category facets with `id`, `label`, and `count`.</ResponseField>
-    <ResponseField name="attributes" type="object[]">Attribute facets with `handle`, `label`, and value counts.</ResponseField>
-  </Expandable>
-</ResponseField>
-<RequestExample>
-```bash cURL
-curl -X POST 'http://localhost:9000/store/search' \
-  -H 'Content-Type: application/json' \
-  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
-  -d '{"q": "linen shirt", "limit": 12, "region_id": "reg_01JB2K4S1T"}'
-```
-```ts JS Client
-const { hits, count, facets } = await client.store.search.mutate({
-  q: "linen shirt",
-  limit: 12,
-  region_id: "reg_01JB2K4S1T",
-})
-```
-</RequestExample>
-<ResponseExample>
-```json 200
-{
-  "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 }]
-      }
-    ]
-  }
-}
-```
-</ResponseExample>