@mercurjs/docs 2.2.0-canary.40

package/content/references/api/admin/products/reject-product.mdx

@@ -0,0 +1,59 @@
+---
+title: "Reject Product"
+api: "POST /admin/products/{id}/reject"
+description: "Reject a proposed product."
+---
+
+Rejects the product's publish request and returns the updated product.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</ParamField>
+
+## Body parameters
+
+<ParamField body="message" type="string">Rejection reason shared with the vendor.</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">Product title.</ResponseField>
+    <ResponseField name="status" type="string">Product status after rejection.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/reject' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Images are too low resolution"}'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.$id.reject.mutate({
+  $id: "prod_01HXYZABCDEF",
+  message: "Images are too low resolution",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "status": "rejected",
+    "updated_at": "2026-06-02T09:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/products/request-product-changes.mdx

@@ -0,0 +1,59 @@
+---
+title: "Request Product Changes"
+api: "POST /admin/products/{id}/request-changes"
+description: "Ask the vendor to revise a product before it can be published."
+---
+
+Flags the product as requiring action and records a message for the vendor.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</ParamField>
+
+## Body parameters
+
+<ParamField body="message" type="string">Message describing the requested changes, shared with the vendor.</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">Product title.</ResponseField>
+    <ResponseField name="status" type="string">Current product status.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/request-changes' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Please add size measurements to the description"}'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.$id.requestChanges.mutate({
+  $id: "prod_01HXYZABCDEF",
+  message: "Please add size measurements to the description",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "status": "proposed",
+    "updated_at": "2026-06-02T09:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/products/retrieve-product-variant.mdx

@@ -0,0 +1,73 @@
+---
+title: "Retrieve Product Variant"
+api: "GET /admin/products/{id}/variants/{variant_id}"
+description: "Retrieve a single variant of a product."
+---
+
+Returns one variant scoped to the given product.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+<ParamField path="variant_id" type="string" required>The variant's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</ParamField>
+
+## Response
+
+<ResponseField name="variant" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The variant's ID.</ResponseField>
+    <ResponseField name="title" type="string">Variant title.</ResponseField>
+    <ResponseField name="sku" type="string">Variant SKU.</ResponseField>
+    <ResponseField name="ean" type="string">Variant EAN.</ResponseField>
+    <ResponseField name="upc" type="string">Variant UPC.</ResponseField>
+    <ResponseField name="barcode" type="string">Variant barcode.</ResponseField>
+    <ResponseField name="variant_rank" type="number">Sort rank of the variant.</ResponseField>
+    <ResponseField name="weight" type="number">Variant weight.</ResponseField>
+    <ResponseField name="length" type="number">Variant length.</ResponseField>
+    <ResponseField name="height" type="number">Variant height.</ResponseField>
+    <ResponseField name="width" type="number">Variant width.</ResponseField>
+    <ResponseField name="origin_country" type="string">Country of origin.</ResponseField>
+    <ResponseField name="material" type="string">Variant material.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the parent product.</ResponseField>
+    <ResponseField name="manage_inventory" type="boolean">Whether inventory is tracked for the variant.</ResponseField>
+    <ResponseField name="allow_backorder" type="boolean">Whether the variant can be ordered when out of stock.</ResponseField>
+    <ResponseField name="options" type="object[]">The variant's option values.</ResponseField>
+    <ResponseField name="metadata" type="object">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/variants/variant_01HXYZABCDEF' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { variant } = await client.admin.products.$id.variants.$variant_id.query({
+  $id: "prod_01HXYZABCDEF",
+  $variant_id: "variant_01HXYZABCDEF",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "variant": {
+    "id": "variant_01HXYZABCDEF",
+    "title": "M",
+    "sku": "LS-M",
+    "product_id": "prod_01HXYZABCDEF",
+    "manage_inventory": false,
+    "allow_backorder": false,
+    "variant_rank": 0
+  }
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,96 @@
+---
+title: "Retrieve Product"
+api: "GET /admin/products/{id}"
+description: "Retrieve a master catalog product by ID."
+---
+
+Returns a single product with its variants, attribute values, and product-scoped attributes.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</ParamField>
+<ParamField query="seller_id" type="string">Scope offer data (when requested via `fields`) to a single seller.</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">Product title.</ResponseField>
+    <ResponseField name="subtitle" type="string">Product subtitle.</ResponseField>
+    <ResponseField name="status" type="string">One of `draft`, `proposed`, `published`, `rejected`.</ResponseField>
+    <ResponseField name="description" type="string">Product description.</ResponseField>
+    <ResponseField name="handle" type="string">Unique URL-safe handle.</ResponseField>
+    <ResponseField name="is_giftcard" type="boolean">Whether the product is a gift card.</ResponseField>
+    <ResponseField name="discountable" type="boolean">Whether discounts can apply to the product.</ResponseField>
+    <ResponseField name="thumbnail" type="string">URL of the product thumbnail.</ResponseField>
+    <ResponseField name="collection" type="object">The collection with `id`, `title`, and `handle`.</ResponseField>
+    <ResponseField name="categories" type="object[]">Categories with `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="variants" type="object[]">Variants with `id`, `title`, `sku`, `manage_inventory`, `allow_backorder`, and `variant_rank`.</ResponseField>
+    <ResponseField name="product_attribute_values" type="object[]">
+      Attribute values selected on the product.
+      <Expandable title="properties">
+        <ResponseField name="id" type="string">The value's ID.</ResponseField>
+        <ResponseField name="name" type="string">Value name.</ResponseField>
+        <ResponseField name="rank" type="number">Sort rank.</ResponseField>
+        <ResponseField name="attribute" type="object">The parent attribute with `id`, `name`, `handle`, `type`, `is_variant_axis`, `is_required`, `rank`, and its full `values` list.</ResponseField>
+      </Expandable>
+    </ResponseField>
+    <ResponseField name="scoped_attributes" type="object[]">
+      Product-scoped (inline) attributes.
+      <Expandable title="properties">
+        <ResponseField name="id" type="string">The attribute's ID.</ResponseField>
+        <ResponseField name="name" type="string">Attribute name.</ResponseField>
+        <ResponseField name="handle" type="string">Attribute handle.</ResponseField>
+        <ResponseField name="type" type="string">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ResponseField>
+        <ResponseField name="is_variant_axis" type="boolean">Whether the attribute drives variant generation.</ResponseField>
+        <ResponseField name="values" type="object[]">Values with `id`, `name`, and `rank`.</ResponseField>
+      </Expandable>
+    </ResponseField>
+    <ResponseField name="attributes" type="object[]">Computed attribute groups, each with the selected `values` and the attribute's full `all_values`.</ResponseField>
+    <ResponseField name="metadata" type="object">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/products/prod_01HXYZABCDEF' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.$id.query({
+  $id: "prod_01HXYZABCDEF",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "handle": "linen-shirt",
+    "status": "published",
+    "variants": [
+      { "id": "variant_01HXYZABCDEF", "title": "M", "sku": "LS-M", "variant_rank": 0 }
+    ],
+    "product_attribute_values": [
+      {
+        "id": "pattrval_01HXYZABCDEF",
+        "name": "Linen",
+        "attribute": { "id": "pattr_01HXYZABCDEF", "name": "Material", "type": "single_select" }
+      }
+    ],
+    "scoped_attributes": []
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/products/set-product-sellers.mdx

@@ -0,0 +1,47 @@
+---
+title: "Set Product Sellers"
+api: "POST /admin/products/{id}/sellers"
+description: "Manage which sellers are eligible to sell a product."
+---
+
+Links or unlinks sellers from the product to control selling eligibility.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="add" type="string[]">IDs of sellers to link to the product.</ParamField>
+<ParamField body="remove" type="string[]">IDs of sellers to unlink from the product.</ParamField>
+
+## Response
+
+<ResponseField name="id" type="string">The product's ID.</ResponseField>
+<ResponseField name="object" type="string">Always `product`.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/sellers' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"add": ["sel_01HXYZABCDEF"], "remove": ["sel_01HXYZABCDEG"]}'
+```
+
+```ts JS Client
+const result = await client.admin.products.$id.sellers.mutate({
+  $id: "prod_01HXYZABCDEF",
+  add: ["sel_01HXYZABCDEF"],
+  remove: ["sel_01HXYZABCDEG"],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "id": "prod_01HXYZABCDEF",
+  "object": "product"
+}
+```
+</ResponseExample>

package/content/references/api/admin/products/update-product-variant.mdx

@@ -0,0 +1,89 @@
+---
+title: "Update Product Variant"
+api: "POST /admin/products/{id}/variants/{variant_id}"
+description: "Update a variant of a product."
+---
+
+Updates the variant and returns the parent product.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+<ParamField path="variant_id" type="string" required>The variant's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="title" type="string">Variant title.</ParamField>
+<ParamField body="sku" type="string">Variant SKU.</ParamField>
+<ParamField body="ean" type="string">Variant EAN.</ParamField>
+<ParamField body="upc" type="string">Variant UPC.</ParamField>
+<ParamField body="isbn" type="string">Variant ISBN.</ParamField>
+<ParamField body="asin" type="string">Variant ASIN.</ParamField>
+<ParamField body="gtin" type="string">Variant GTIN.</ParamField>
+<ParamField body="barcode" type="string">Variant barcode.</ParamField>
+<ParamField body="hs_code" type="string">Harmonized System code.</ParamField>
+<ParamField body="mid_code" type="string">Manufacturer identification code.</ParamField>
+<ParamField body="thumbnail" type="string">URL of the variant thumbnail.</ParamField>
+<ParamField body="variant_rank" type="number">Sort rank of the variant.</ParamField>
+<ParamField body="weight" type="number">Variant weight.</ParamField>
+<ParamField body="length" type="number">Variant length.</ParamField>
+<ParamField body="height" type="number">Variant height.</ParamField>
+<ParamField body="width" type="number">Variant width.</ParamField>
+<ParamField body="origin_country" type="string">Country of origin.</ParamField>
+<ParamField body="material" type="string">Variant material.</ParamField>
+<ParamField body="prices" type="object[]">
+  Variant prices.
+  <Expandable title="properties">
+    <ParamField body="id" type="string">Existing price ID to update.</ParamField>
+    <ParamField body="currency_code" type="string">Price currency code.</ParamField>
+    <ParamField body="amount" type="number">Price amount.</ParamField>
+    <ParamField body="min_quantity" type="number">Minimum quantity for the price to apply.</ParamField>
+    <ParamField body="max_quantity" type="number">Maximum quantity for the price to apply.</ParamField>
+    <ParamField body="rules" type="object">Map of rule attribute to value.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="options" type="object">Map of option title to option value.</ParamField>
+<ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed to workflow hooks.</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">Product title.</ResponseField>
+    <ResponseField name="variants" type="object[]">All variants, including the updated one.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/variants/variant_01HXYZABCDEF' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"sku": "LS-M-2026"}'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.$id.variants.$variant_id.mutate({
+  $id: "prod_01HXYZABCDEF",
+  $variant_id: "variant_01HXYZABCDEF",
+  sku: "LS-M-2026",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "variants": [
+      { "id": "variant_01HXYZABCDEF", "title": "M", "sku": "LS-M-2026" }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/products/update-product.mdx

@@ -0,0 +1,133 @@
+---
+title: "Update Product"
+api: "POST /admin/products/{id}"
+description: "Update a master catalog product."
+---
+
+Updates the product's details; only the provided fields are changed.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="title" type="string">Product title.</ParamField>
+<ParamField body="subtitle" type="string">Product subtitle.</ParamField>
+<ParamField body="description" type="string">Product description.</ParamField>
+<ParamField body="handle" type="string">Unique URL-safe handle.</ParamField>
+<ParamField body="status" type="string">One of `draft`, `proposed`, `published`, `rejected`.</ParamField>
+<ParamField body="is_giftcard" type="boolean">Whether the product is a gift card.</ParamField>
+<ParamField body="discountable" type="boolean">Whether discounts can apply to the product.</ParamField>
+<ParamField body="thumbnail" type="string">URL of the product thumbnail.</ParamField>
+<ParamField body="images" type="object[]">
+  Product images; replaces the existing set.
+  <Expandable title="properties">
+    <ParamField body="id" type="string">Existing image ID to keep.</ParamField>
+    <ParamField body="url" type="string" required>Image URL.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="external_id" type="string">ID of the product in an external system.</ParamField>
+<ParamField body="type_id" type="string">ID of the product type.</ParamField>
+<ParamField body="collection_id" type="string">ID of the collection to assign the product to.</ParamField>
+<ParamField body="categories" type="object[]">
+  Categories to assign; replaces the existing set.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Category ID.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="tags" type="object[]">
+  Tags to assign; replaces the existing set.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Tag ID.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="options" type="object[]">
+  Product options; replaces the existing set.
+  <Expandable title="properties">
+    <ParamField body="title" type="string" required>Option title.</ParamField>
+    <ParamField body="values" type="string[]" required>Possible option values.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="variants" type="object[]">
+  Variants to upsert; include `id` to update an existing variant.
+  <Expandable title="properties">
+    <ParamField body="id" type="string">Existing variant ID.</ParamField>
+    <ParamField body="title" type="string">Variant title.</ParamField>
+    <ParamField body="sku" type="string">Variant SKU.</ParamField>
+    <ParamField body="ean" type="string">Variant EAN.</ParamField>
+    <ParamField body="upc" type="string">Variant UPC.</ParamField>
+    <ParamField body="isbn" type="string">Variant ISBN.</ParamField>
+    <ParamField body="asin" type="string">Variant ASIN.</ParamField>
+    <ParamField body="gtin" type="string">Variant GTIN.</ParamField>
+    <ParamField body="barcode" type="string">Variant barcode.</ParamField>
+    <ParamField body="hs_code" type="string">Harmonized System code.</ParamField>
+    <ParamField body="mid_code" type="string">Manufacturer identification code.</ParamField>
+    <ParamField body="thumbnail" type="string">URL of the variant thumbnail.</ParamField>
+    <ParamField body="variant_rank" type="number">Sort rank of the variant.</ParamField>
+    <ParamField body="weight" type="number">Variant weight.</ParamField>
+    <ParamField body="length" type="number">Variant length.</ParamField>
+    <ParamField body="height" type="number">Variant height.</ParamField>
+    <ParamField body="width" type="number">Variant width.</ParamField>
+    <ParamField body="origin_country" type="string">Country of origin.</ParamField>
+    <ParamField body="material" type="string">Variant material.</ParamField>
+    <ParamField body="prices" type="object[]">Prices with `id`, `currency_code`, `amount`, `min_quantity`, `max_quantity`, and `rules`.</ParamField>
+    <ParamField body="options" type="object">Map of option title to option value.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="weight" type="number">Product weight.</ParamField>
+<ParamField body="length" type="number">Product length.</ParamField>
+<ParamField body="height" type="number">Product height.</ParamField>
+<ParamField body="width" type="number">Product width.</ParamField>
+<ParamField body="hs_code" type="string">Harmonized System code.</ParamField>
+<ParamField body="mid_code" type="string">Manufacturer identification code.</ParamField>
+<ParamField body="origin_country" type="string">Country of origin.</ParamField>
+<ParamField body="material" type="string">Product material.</ParamField>
+<ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed to workflow hooks.</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">Product title.</ResponseField>
+    <ResponseField name="status" type="string">One of `draft`, `proposed`, `published`, `rejected`.</ResponseField>
+    <ResponseField name="variants" type="object[]">Product variants.</ResponseField>
+    <ResponseField name="product_attribute_values" type="object[]">Attribute values selected on the product.</ResponseField>
+    <ResponseField name="scoped_attributes" type="object[]">Product-scoped (inline) attributes.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/products/prod_01HXYZABCDEF' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"title": "Linen Shirt v2", "status": "published"}'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.$id.mutate({
+  $id: "prod_01HXYZABCDEF",
+  title: "Linen Shirt v2",
+  status: "published",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt v2",
+    "handle": "linen-shirt",
+    "status": "published",
+    "updated_at": "2026-06-02T09:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/admin/sellers/add-seller-member.mdx

@@ -0,0 +1,63 @@
+---
+title: "Add Seller Member"
+api: "POST /admin/sellers/{id}/members"
+description: "Add an existing member to a seller's team."
+---
+
+Links an existing member to the seller with the given role.
+
+<Note>
+To add someone who does not have a member record yet, use [Invite Seller Member](/rc/references/api/admin/sellers/invite-seller-member) instead.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The seller's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="member_id" type="string" required>ID of the existing member to add.</ParamField>
+<ParamField body="role_id" type="string" required>ID of the role to assign.</ParamField>
+
+## Response
+
+<ResponseField name="seller_member" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller member's ID.</ResponseField>
+    <ResponseField name="seller_id" type="string">ID of the seller.</ResponseField>
+    <ResponseField name="member_id" type="string">ID of the linked member.</ResponseField>
+    <ResponseField name="is_owner" type="boolean">Whether this member owns the seller account.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/admin/sellers/sel_01HXYZABCDEF/members' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"member_id": "mem_01HXYZMEMBB", "role_id": "role_01HXYZROLEAA"}'
+```
+
+```ts JS Client
+const { seller_member } = await client.admin.sellers.$id.members.mutate({
+  $id: "sel_01HXYZABCDEF",
+  member_id: "mem_01HXYZMEMBB",
+  role_id: "role_01HXYZROLEAA",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201
+{
+  "seller_member": {
+    "id": "selmem_01HXYZSMBB",
+    "seller_id": "sel_01HXYZABCDEF",
+    "member_id": "mem_01HXYZMEMBB",
+    "is_owner": false,
+    "created_at": "2026-06-15T09:00:00.000Z"
+  }
+}
+```
+</ResponseExample>