@mercurjs/docs 2.2.0-canary.40

package/content/references/api/store/products/retrieve-product.mdx

@@ -0,0 +1,107 @@
+---
+title: "Retrieve Product"
+api: "GET /store/products/{id}"
+description: "Retrieve a published product by ID."
+---
+
+Returns a single published product; a `404` is returned if the product is unpublished or its seller is not visible.
+
+<Note>
+  Customer authentication is optional. When a customer token is provided, the customer's group memberships enter the pricing context used for `variants.calculated_price`. Prices are computed only when `variants.calculated_price` is requested in `fields` (or `region_id` is passed) and reflect the cheapest offer per variant.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="region_id" type="string">
+  Region used to build the pricing context for `variants.calculated_price`.
+</ParamField>
+
+<ParamField query="currency_code" type="string">
+  Currency used in the pricing context.
+</ParamField>
+
+## Response
+
+<ResponseField name="product" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The product's ID.</ResponseField>
+    <ResponseField name="title" type="string">The product's title.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="status" type="string">Always `published` on the store API.</ResponseField>
+    <ResponseField name="description" type="string | null">The product's description.</ResponseField>
+    <ResponseField name="thumbnail" type="string | null">Thumbnail URL.</ResponseField>
+    <ResponseField name="collection" type="object | null">The product's collection.</ResponseField>
+    <ResponseField name="type" type="object | null">The product's type.</ResponseField>
+    <ResponseField name="tags" type="object[]">The product's tags.</ResponseField>
+    <ResponseField name="images" type="object[]">The product's images.</ResponseField>
+    <ResponseField name="categories" type="object[]">The product's categories.</ResponseField>
+    <ResponseField name="options" type="object[]">Product options with their values.</ResponseField>
+    <ResponseField name="variants" type="object[]">
+      Product variants; `calculated_price` and `offer_id` are added when requested and reflect the cheapest offer.
+    </ResponseField>
+    <ResponseField name="product_attribute_values" type="object[]">Attribute values assigned to the product.</ResponseField>
+    <ResponseField name="scoped_attributes" type="object[]">Attributes scoped to this product, with their values.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/products/prod_01JB2K5M8N?region_id=reg_01JB2K4S1T&fields=*variants.calculated_price' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { product } = await client.store.products.$id.query({
+  $id: "prod_01JB2K5M8N",
+  region_id: "reg_01JB2K4S1T",
+  fields: "*variants.calculated_price",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01JB2K5M8N",
+    "title": "Linen Shirt",
+    "handle": "linen-shirt",
+    "status": "published",
+    "description": "A breathable linen shirt.",
+    "thumbnail": "https://cdn.example.com/linen-shirt.png",
+    "collection": null,
+    "type": null,
+    "tags": [],
+    "images": [],
+    "categories": [{ "id": "pcat_01JB2K6A2B", "name": "Shirts" }],
+    "options": [{ "id": "opt_01JB2K6C3D", "title": "Size", "values": [{ "value": "M" }] }],
+    "variants": [
+      {
+        "id": "variant_01JB2K6E4F",
+        "title": "M",
+        "offer_id": "offer_01JB2K6G5H",
+        "calculated_price": {
+          "calculated_amount": 4500,
+          "original_amount": 5000,
+          "currency_code": "eur"
+        }
+      }
+    ],
+    "product_attribute_values": [],
+    "scoped_attributes": [],
+    "metadata": null
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store/search/search.mdx

@@ -0,0 +1,136 @@
+---
+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>

package/content/references/api/store/sellers/list-sellers.mdx

@@ -0,0 +1,105 @@
+---
+title: "List Sellers"
+api: "GET /store/sellers"
+description: "Retrieve open sellers visible on the storefront."
+---
+
+Returns a paginated list of sellers; only sellers with status `open` that are outside any scheduled closure window (`closed_from` / `closed_to`) are included.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  Maximum number of sellers to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  Number of sellers to skip before collecting results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  Field to sort by, prefixed with `-` for descending order.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Free-text search term applied to seller fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by one or more seller IDs.
+</ParamField>
+
+<ParamField query="name" type="string | string[]">
+  Filter by one or more seller names.
+</ParamField>
+
+<ParamField query="handle" type="string">
+  Filter by seller handle.
+</ParamField>
+
+<ParamField query="is_premium" type="boolean">
+  Filter premium sellers.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+## Response
+
+<ResponseField name="sellers" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller's ID.</ResponseField>
+    <ResponseField name="name" type="string">The seller's display name.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="description" type="string | null">The seller's storefront description.</ResponseField>
+    <ResponseField name="logo" type="string | null">Logo URL.</ResponseField>
+    <ResponseField name="banner" type="string | null">Banner image URL.</ResponseField>
+    <ResponseField name="is_premium" type="boolean">Whether the seller has premium status.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching sellers.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped sellers.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned sellers.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/sellers?limit=20' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { sellers, count } = await client.store.sellers.query({ limit: 20 })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "sellers": [
+    {
+      "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
+    }
+  ],
+  "count": 12,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>

package/content/references/api/store/sellers/retrieve-seller.mdx

@@ -0,0 +1,62 @@
+---
+title: "Retrieve Seller"
+api: "GET /store/sellers/{id}"
+description: "Retrieve an open seller by ID."
+---
+
+Returns a single seller; sellers that are not `open` or are inside a scheduled closure window return a `404`.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The seller's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Response
+
+<ResponseField name="seller" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller's ID.</ResponseField>
+    <ResponseField name="name" type="string">The seller's display name.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="description" type="string | null">The seller's storefront description.</ResponseField>
+    <ResponseField name="logo" type="string | null">Logo URL.</ResponseField>
+    <ResponseField name="banner" type="string | null">Banner image URL.</ResponseField>
+    <ResponseField name="is_premium" type="boolean">Whether the seller has premium status.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/sellers/sel_01JB2K8A1B' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { seller } = await client.store.sellers.$id.query({ $id: "sel_01JB2K8A1B" })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "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
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store/shipping-options/list-shipping-options.mdx

@@ -0,0 +1,74 @@
+---
+title: "List Shipping Options"
+api: "GET /store/shipping-options"
+description: "Retrieve available shipping options for a cart, grouped by seller."
+---
+
+Returns the shipping options that can fulfill the given cart, grouped by the seller of the items each option applies to.
+
+## Query parameters
+
+<ParamField query="cart_id" type="string" required>
+  ID of the cart to list shipping options for.
+</ParamField>
+
+<ParamField query="is_return" type="boolean">
+  Set to `true` to list return shipping options.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include on each shipping option; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Response
+
+<ResponseField name="shipping_options" type="object">
+  Map of seller ID to the shipping options available for that seller's items.
+  <Expandable title="properties">
+    <ResponseField name="{seller_id}" type="object[]">
+      Shipping options for the seller, each with `id`, `name`, `price_type`, `provider_id`, calculated `amount`, and `type`.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/shipping-options?cart_id=cart_01JB2KB1CD' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { shipping_options } = await client.store.shippingOptions.query({
+  cart_id: "cart_01JB2KB1CD",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "shipping_options": {
+    "sel_01JB2K8A1B": [
+      {
+        "id": "so_01JB2KC4GH",
+        "name": "Standard Shipping",
+        "price_type": "flat",
+        "provider_id": "manual_manual",
+        "amount": 900,
+        "type": { "label": "Standard", "code": "standard" }
+      }
+    ],
+    "sel_01JB2KF9ST": [
+      {
+        "id": "so_01JB2KG0UV",
+        "name": "Express",
+        "price_type": "flat",
+        "provider_id": "manual_manual",
+        "amount": 1500,
+        "type": { "label": "Express", "code": "express" }
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store.mdx

@@ -0,0 +1,67 @@
+---
+title: "Store API"
+description: "Storefront routes under /store/* — discovery, multi-vendor carts, checkout, and order groups."
+---
+
+The Store API is what a storefront talks to. It extends Medusa's store routes with marketplace discovery (sellers, offers, search) and replaces the cart completion flow with the multi-vendor order-group split.
+
+Most routes are public; customer authentication requirements are noted per group. See [API conventions](/rc/references/api/conventions) for pagination and field selection.
+
+## Products and discovery
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/store/products` | List published products (filtered to sellers visible to the shopper) |
+| `GET` | `/store/products/:id` | Retrieve a product |
+| `GET` | `/store/product-categories[/:id]` | Category tree with media and icons |
+| `GET` | `/store/product-attributes[/:id]` | Filterable attributes for building facet UIs |
+
+## Search
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/store/search` | Query the search index across products and offers |
+
+Request body: `q`, `limit` (default 12, max 100), `offset`, pricing context (`region_id`, `country_code`, `province`), and provider-owned `filters`. Response: `{ hits, count, limit, offset, facets }` with pre-labelled collection, category, and attribute facets. See the [Search module](/rc/references/modules/search) for document shapes and filter semantics.
+
+## Sellers
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/store/sellers` | List public seller storefronts (only `open` sellers outside a closure window) |
+| `GET` | `/store/sellers/:id` | Retrieve a seller storefront |
+
+## Offers
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/store/offers` | List offers, with per-offer calculated prices |
+| `GET` | `/store/offers/:id` | Retrieve an offer |
+
+## Carts and checkout
+
+Mercur overrides the cart routes so a single cart can span multiple sellers:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/store/carts/:id/line-items` | Add a line item (offer-aware, multi-seller) |
+| `POST` | `/store/carts/:id/shipping-methods` | Add per-seller shipping methods |
+| `GET` | `/store/shipping-options` | Shipping options available for the cart, grouped by seller |
+| `POST` | `/store/carts/:id/promotions` | Apply promotions |
+| `POST` | `/store/carts/:id/complete` | Complete the cart — splits it into per-seller orders under an order group |
+
+## Order groups
+
+Customer authentication **required**.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/store/order-groups` | The customer's order groups |
+| `GET` | `/store/order-groups/:id` | An order group with its per-seller child orders |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Order groups" href="/rc/learn/order-groups" />
+  <Card title="Search module" href="/rc/references/modules/search" />
+</CardGroup>

package/content/references/api/vendor/members/accept-member-invite.mdx

@@ -0,0 +1,65 @@
+---
+title: "Accept Member Invite"
+api: "POST /vendor/members/invites/accept"
+description: "Accept a seller team invite using its token."
+---
+
+Accepts a member invite and joins the inviting seller's team.
+
+<Note>
+  This is a public route — no `Authorization` or `x-seller-id` header is required. The invite is identified by the `invite_token` sent in the invitation email.
+</Note>
+
+## Body parameters
+
+<ParamField body="invite_token" type="string" required>
+  The token from the invitation email.
+</ParamField>
+
+<ParamField body="first_name" type="string">
+  First name for the new member profile.
+</ParamField>
+
+<ParamField body="last_name" type="string">
+  Last name for the new member profile.
+</ParamField>
+
+## Response
+
+<ResponseField name="member" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The member's ID.</ResponseField>
+    <ResponseField name="first_name" type="string">The member's first name.</ResponseField>
+    <ResponseField name="last_name" type="string">The member's last name.</ResponseField>
+    <ResponseField name="email" type="string">The member's email.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/members/invites/accept' \
+  -H 'Content-Type: application/json' \
+  -d '{"invite_token": "<invite_token>", "first_name": "John", "last_name": "Roe"}'
+```
+
+```ts JS Client
+const { member } = await client.vendor.members.invites.accept.mutate({
+  invite_token: "<invite_token>",
+  first_name: "John",
+  last_name: "Roe",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "member": {
+    "id": "mem_01HXYZ",
+    "first_name": "John",
+    "last_name": "Roe",
+    "email": "teammate@acme.com"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/members/retrieve-current-member.mdx

@@ -0,0 +1,51 @@
+---
+title: "Retrieve Current Member"
+api: "GET /vendor/members/me"
+description: "Retrieve the authenticated member's profile for the active seller."
+---
+
+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.
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response.
+</ParamField>
+
+## Response
+
+<ResponseField name="seller_member" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller member's ID.</ResponseField>
+    <ResponseField name="is_owner" type="boolean">Whether the member owns the seller account.</ResponseField>
+    <ResponseField name="member" type="object">The member's profile (first name, last name, email, locale).</ResponseField>
+    <ResponseField name="rbac_role" type="object">The member's role for this seller.</ResponseField>
+    <ResponseField name="seller" type="object">The active seller, with `address`, `payment_details`, and `professional_details`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/members/me' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { seller_member } = await client.vendor.members.me.query()
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "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" }
+  }
+}
+```
+</ResponseExample>