@mercurjs/docs 2.2.0-canary.40

package/content/references/api/vendor/products/create-product.mdx

@@ -0,0 +1,197 @@
+---
+title: "Create Product"
+api: "POST /vendor/products"
+description: "Create a new product owned by the seller."
+---
+
+Creates a product; when no status is provided it is created with status `proposed`.
+
+<Note>
+  When the product request flow is enabled, `status` may only be `draft` or `proposed` — publishing requires operator approval.
+</Note>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the returned product. Prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="title" type="string" required>
+  The product's title.
+</ParamField>
+
+<ParamField body="subtitle" type="string">
+  The product's subtitle.
+</ParamField>
+
+<ParamField body="description" type="string">
+  The product's description.
+</ParamField>
+
+<ParamField body="status" type="string" default="proposed">
+  One of `draft`, `proposed`, `published`, `rejected`. Restricted to `draft` / `proposed` when the product request flow is enabled.
+</ParamField>
+
+<ParamField body="is_giftcard" type="boolean" default="false">
+  Whether the product is a gift card.
+</ParamField>
+
+<ParamField body="discountable" type="boolean" default="true">
+  Whether discounts can apply to the product.
+</ParamField>
+
+<ParamField body="images" type="object[]">
+  <Expandable title="properties">
+    <ParamField body="url" type="string" required>Image URL.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="thumbnail" type="string">
+  URL of the product's thumbnail image.
+</ParamField>
+
+<ParamField body="handle" type="string">
+  The product's URL handle; generated from the title when omitted.
+</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 the product belongs to.
+</ParamField>
+
+<ParamField body="categories" type="object[]">
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Category ID.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="tags" type="object[]">
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Tag ID.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="options" type="object[]">
+  <Expandable title="properties">
+    <ParamField body="title" type="string" required>Option title, e.g. `Size`.</ParamField>
+    <ParamField body="values" type="string[]" required>Allowed option values.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="attributes" type="object[]">
+  Product attribute assignments; each entry references an existing attribute by `id` or defines one inline by `title`.
+  <Expandable title="properties">
+    <ParamField body="id" type="string">Existing attribute ID (referencing form).</ParamField>
+    <ParamField body="value_ids" type="string[]">IDs of attribute values to select (referencing form).</ParamField>
+    <ParamField body="value" type="string | number | boolean">Scalar value for `text`, `unit`, or `toggle` attributes.</ParamField>
+    <ParamField body="title" type="string">Attribute title (inline form).</ParamField>
+    <ParamField body="type" type="string">One of `single_select`, `multi_select`, `text`, `toggle`, `unit` (inline form).</ParamField>
+    <ParamField body="values" type="string[]">Value names to create and select (inline form).</ParamField>
+    <ParamField body="is_variant_axis" type="boolean">Whether the attribute drives variant combinations (inline form).</ParamField>
+    <ParamField body="is_filterable" type="boolean">Whether the attribute is filterable (inline form).</ParamField>
+    <ParamField body="is_required" type="boolean">Whether the attribute is required (inline form).</ParamField>
+    <ParamField body="description" type="string">Attribute description (inline form).</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value pairs (inline form).</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="variants" type="object[]">
+  <Expandable title="properties">
+    <ParamField body="title" type="string" required>Variant title.</ParamField>
+    <ParamField body="sku" type="string">Variant SKU.</ParamField>
+    <ParamField body="ean" type="string">EAN barcode.</ParamField>
+    <ParamField body="upc" type="string">UPC barcode.</ParamField>
+    <ParamField body="isbn" type="string">ISBN code.</ParamField>
+    <ParamField body="asin" type="string">Amazon ASIN.</ParamField>
+    <ParamField body="gtin" type="string">GTIN code.</ParamField>
+    <ParamField body="barcode" type="string">Generic barcode.</ParamField>
+    <ParamField body="hs_code" type="string">Harmonized System code.</ParamField>
+    <ParamField body="mid_code" type="string">Manufacturer ID code.</ParamField>
+    <ParamField body="variant_rank" type="number">Sort rank of the variant.</ParamField>
+    <ParamField body="weight" type="number">Weight of the variant.</ParamField>
+    <ParamField body="length" type="number">Length of the variant.</ParamField>
+    <ParamField body="height" type="number">Height of the variant.</ParamField>
+    <ParamField body="width" type="number">Width of the variant.</ParamField>
+    <ParamField body="origin_country" type="string">Country of origin.</ParamField>
+    <ParamField body="material" type="string">Material of the variant.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value pairs.</ParamField>
+    <ParamField body="options" type="object">Option title to value mapping, e.g. `{"Size": "M"}`.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="weight" type="number">Weight of the product.</ParamField>
+<ParamField body="length" type="number">Length of the product.</ParamField>
+<ParamField body="height" type="number">Height of the product.</ParamField>
+<ParamField body="width" type="number">Width of the product.</ParamField>
+<ParamField body="hs_code" type="string">Harmonized System code.</ParamField>
+<ParamField body="mid_code" type="string">Manufacturer ID code.</ParamField>
+<ParamField body="origin_country" type="string">Country of origin.</ParamField>
+<ParamField body="material" type="string">Material of the product.</ParamField>
+<ParamField body="metadata" type="object">Custom key-value pairs.</ParamField>
+<ParamField body="additional_data" type="object">Extra 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">The product's title.</ResponseField>
+    <ResponseField name="status" type="string">The product's status (`proposed` unless overridden).</ResponseField>
+    <ResponseField name="handle" type="string">The product's URL handle.</ResponseField>
+    <ResponseField name="variants" type="object[]">The created variants.</ResponseField>
+    <ResponseField name="attributes" type="object[]">The product's attribute assignments.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+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" } }
+    ]
+  }'
+```
+
+```ts JS Client
+const { product } = await client.vendor.products.mutate({
+  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" } },
+  ],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201
+{
+  "product": {
+    "id": "prod_01HXYZ",
+    "title": "Acme T-Shirt",
+    "status": "proposed",
+    "handle": "acme-t-shirt",
+    "variants": [
+      { "id": "variant_01HXYZ", "title": "M", "sku": "ACME-SHIRT-M" }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/delete-product-variant.mdx

@@ -0,0 +1,68 @@
+---
+title: "Delete Product Variant"
+api: "DELETE /vendor/products/{id}/variants/{variant_id}"
+description: "Stage the removal of a product variant as a change request."
+---
+
+Stages a `VARIANT_REMOVE` operation as a pending change request instead of deleting the variant directly.
+
+<Note>
+  The endpoint responds with `202 Accepted` and a `product_change` record; the variant remains until the change is confirmed.
+</Note>
+
+## 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>
+
+## Response
+
+<ResponseField name="product_change" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The change request's ID.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the product the change targets.</ResponseField>
+    <ResponseField name="status" type="string">One of `pending`, `confirmed`, `declined`, `canceled`.</ResponseField>
+    <ResponseField name="actions" type="object[]">Staged operations, each with `id`, `action` (`VARIANT_REMOVE`), `details`, `ordering`, and `applied`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X DELETE 'http://localhost:9000/vendor/products/prod_01HXYZ/variants/variant_01HXYZ' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { product_change } =
+  await client.vendor.products.$id.variants.$variant_id.delete({
+    $id: "prod_01HXYZ",
+    $variant_id: "variant_01HXYZ",
+  })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 202
+{
+  "product_change": {
+    "id": "prodch_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "status": "pending",
+    "actions": [
+      {
+        "id": "prodchact_01HXYZ",
+        "action": "VARIANT_REMOVE",
+        "details": { "variant_id": "variant_01HXYZ" },
+        "applied": false
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/delete-product.mdx

@@ -0,0 +1,62 @@
+---
+title: "Delete Product"
+api: "DELETE /vendor/products/{id}"
+description: "Stage a product deletion as a change request."
+---
+
+Does not delete the product directly — it stages a pending `PRODUCT_DELETE` change request that an operator confirms or declines.
+
+<Note>
+  The endpoint responds with `202 Accepted` and a `product_change` record; the product remains until the change is confirmed.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_change" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The change request's ID.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the product the change targets.</ResponseField>
+    <ResponseField name="status" type="string">One of `pending`, `confirmed`, `declined`, `canceled`.</ResponseField>
+    <ResponseField name="created_by" type="string">ID of the seller that staged the change.</ResponseField>
+    <ResponseField name="actions" type="object[]">Staged operations, each with `id`, `action` (`PRODUCT_DELETE`), `details`, `ordering`, and `applied`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X DELETE 'http://localhost:9000/vendor/products/prod_01HXYZ' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { product_change } = await client.vendor.products.$id.delete({
+  $id: "prod_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 202
+{
+  "product_change": {
+    "id": "prodch_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "status": "pending",
+    "actions": [
+      {
+        "id": "prodchact_01HXYZ",
+        "action": "PRODUCT_DELETE",
+        "applied": false
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/list-product-variants.mdx

@@ -0,0 +1,114 @@
+---
+title: "List Product Variants"
+api: "GET /vendor/products/{id}/variants"
+description: "Retrieve a paginated list of a product's variants."
+---
+
+Returns the variants belonging to the given product.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  The maximum number of variants to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  The number of variants to skip before returning results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  The field to sort by, e.g. `variant_rank` or `-created_at`.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response. Prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Search term matched against variant fields.
+</ParamField>
+
+<ParamField query="manage_inventory" type="boolean">
+  Filter by whether inventory is managed for the variant.
+</ParamField>
+
+<ParamField query="allow_backorder" type="boolean">
+  Filter by whether backorders are allowed.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$lt`, `$gte`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$lt`, `$gte`, `$lte`.
+</ParamField>
+
+<ParamField query="$and" type="object[]">
+  Join multiple filter objects with a logical AND.
+</ParamField>
+
+<ParamField query="$or" type="object[]">
+  Join multiple filter objects with a logical OR.
+</ParamField>
+
+## Response
+
+<ResponseField name="variants" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The variant's ID.</ResponseField>
+    <ResponseField name="title" type="string">The variant's title.</ResponseField>
+    <ResponseField name="sku" type="string">The variant's SKU.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the parent product.</ResponseField>
+    <ResponseField name="manage_inventory" type="boolean">Whether inventory is managed for the variant.</ResponseField>
+    <ResponseField name="allow_backorder" type="boolean">Whether backorders are allowed.</ResponseField>
+    <ResponseField name="variant_rank" type="number">Sort rank of the variant.</ResponseField>
+    <ResponseField name="options" type="object[]">Selected option values with `id`, `value`, and the parent `option`.</ResponseField>
+    <ResponseField name="images" type="object[]">Variant images with `id`, `url`, and `rank`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching variants.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped variants.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned variants.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/products/prod_01HXYZ/variants?limit=20' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { variants, count } = await client.vendor.products.$id.variants.query({
+  $id: "prod_01HXYZ",
+  limit: 20,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "variants": [
+    {
+      "id": "variant_01HXYZ",
+      "title": "M",
+      "sku": "ACME-SHIRT-M",
+      "product_id": "prod_01HXYZ",
+      "manage_inventory": false,
+      "allow_backorder": false
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/list-products.mdx

@@ -0,0 +1,163 @@
+---
+title: "List Products"
+api: "GET /vendor/products"
+description: "Retrieve a paginated list of products visible to the seller."
+---
+
+Returns products the seller created plus published products that are not restricted from the seller.
+
+<Note>
+  Products are shared master records. This list includes catalog products from other sellers (when published and unrestricted) so you can create offers against them.
+</Note>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  The maximum number of products to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  The number of products to skip before returning results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  The field to sort by, e.g. `created_at` or `-created_at` for descending.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response. Prefix with `+`/`-` to add to or remove from the defaults. Include `variants.offers` to attach the seller's offers to each variant.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Search term matched against product fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by product ID(s).
+</ParamField>
+
+<ParamField query="title" type="string">
+  Filter by product title.
+</ParamField>
+
+<ParamField query="handle" type="string">
+  Filter by product handle.
+</ParamField>
+
+<ParamField query="status" type="string[]">
+  Filter by status. Values: `draft`, `proposed`, `published`, `rejected`.
+</ParamField>
+
+<ParamField query="collection_id" type="string | string[]">
+  Filter by collection ID(s).
+</ParamField>
+
+<ParamField query="type_id" type="string | string[]">
+  Filter by product type ID(s).
+</ParamField>
+
+<ParamField query="category_id" type="string | string[]">
+  Filter by category ID(s).
+</ParamField>
+
+<ParamField query="tag_id" type="string | string[]">
+  Filter by tag ID(s).
+</ParamField>
+
+<ParamField query="sku" type="string">
+  Filter by variant SKU.
+</ParamField>
+
+<ParamField query="ean" type="string">
+  Filter by variant EAN.
+</ParamField>
+
+<ParamField query="upc" type="string">
+  Filter by variant UPC.
+</ParamField>
+
+<ParamField query="barcode" type="string">
+  Filter by variant barcode.
+</ParamField>
+
+<ParamField query="has_offer" type="boolean">
+  Filter to products the seller has (or has not) created an offer for.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$lt`, `$gte`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$lt`, `$gte`, `$lte`.
+</ParamField>
+
+<ParamField query="deleted_at" type="object">
+  Filter by deletion date using operators like `$gt`, `$lt`, `$gte`, `$lte`.
+</ParamField>
+
+<ParamField query="$and" type="object[]">
+  Join multiple filter objects with a logical AND.
+</ParamField>
+
+<ParamField query="$or" type="object[]">
+  Join multiple filter objects with a logical OR.
+</ParamField>
+
+## Response
+
+<ResponseField name="products" 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="status" type="string">One of `draft`, `proposed`, `published`, `rejected`.</ResponseField>
+    <ResponseField name="handle" type="string">The product's URL handle.</ResponseField>
+    <ResponseField name="thumbnail" type="string">URL of the product's thumbnail image.</ResponseField>
+    <ResponseField name="images" type="object[]">The product's images with `id`, `url`, and `rank`.</ResponseField>
+    <ResponseField name="collection" type="object">The associated collection with `id`, `title`, and `handle`.</ResponseField>
+    <ResponseField name="categories" type="object[]">Associated categories with `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="variants" type="object[]">The product's variants with `id`, `title`, `sku`, `manage_inventory`, `allow_backorder`, and `variant_rank`.</ResponseField>
+    <ResponseField name="attributes" type="object[]">Product attributes grouped per attribute with their selected values.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching products.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped products.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned products.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/products?limit=20&status[]=published' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { products, count } = await client.vendor.products.query({
+  limit: 20,
+  status: ["published"],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "products": [
+    {
+      "id": "prod_01HXYZ",
+      "title": "Acme T-Shirt",
+      "status": "published",
+      "handle": "acme-t-shirt",
+      "thumbnail": "https://cdn.example.com/shirt.png",
+      "variants": [
+        { "id": "variant_01HXYZ", "title": "M", "sku": "ACME-SHIRT-M" }
+      ]
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/preview-product.mdx

@@ -0,0 +1,61 @@
+---
+title: "Preview Product Change"
+api: "GET /vendor/products/{id}/preview"
+description: "Retrieve the seller's pending change request for a product."
+---
+
+Returns the seller's `pending` change request for the product, or `null` when there is none.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_change" type="object | null">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The change request's ID.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the product the change targets.</ResponseField>
+    <ResponseField name="status" type="string">Always `pending` for this endpoint.</ResponseField>
+    <ResponseField name="created_by" type="string">ID of the seller that staged the change.</ResponseField>
+    <ResponseField name="actions" type="object[]">Staged operations, each with `id`, `action`, `details`, `ordering`, and `applied`.</ResponseField>
+    <ResponseField name="internal_note" type="string">Internal note attached to the change.</ResponseField>
+    <ResponseField name="external_note" type="string">Note from the operator, e.g. a revision request.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/products/prod_01HXYZ/preview' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { product_change } = await client.vendor.products.$id.preview.query({
+  $id: "prod_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_change": {
+    "id": "prodch_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "status": "pending",
+    "actions": [
+      {
+        "id": "prodchact_01HXYZ",
+        "action": "UPDATE",
+        "details": { "title": "Acme T-Shirt v2" },
+        "applied": false
+      }
+    ]
+  }
+}
+```
+</ResponseExample>