@mercurjs/docs 2.2.0-canary.40

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

@@ -0,0 +1,78 @@
+---
+title: "Create Product Variant"
+api: "POST /admin/products/{id}/variants"
+description: "Add a variant to a product."
+---
+
+Creates a new variant on the product and returns the updated product.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Body parameters
+
+<ParamField body="title" type="string" required>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="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="options" type="object">Map of option title to option value, for example `{"Size": "L"}`.</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 created 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' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"title": "L", "sku": "LS-L", "options": {"Size": "L"}}'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.$id.variants.mutate({
+  $id: "prod_01HXYZABCDEF",
+  title: "L",
+  sku: "LS-L",
+  options: { Size: "L" },
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "variants": [
+      { "id": "variant_01HXYZABCDEF", "title": "M", "sku": "LS-M" },
+      { "id": "variant_01HXYZABCDEG", "title": "L", "sku": "LS-L" }
+    ]
+  }
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,169 @@
+---
+title: "Create Product"
+api: "POST /admin/products"
+description: "Create a master catalog product."
+---
+
+Creates a shared master product that sellers can be made eligible to sell.
+
+<Note>
+Pass `seller_ids` to set which sellers may sell the product. The `attributes` array accepts a unified input: reference an existing catalog attribute by `id`, or create an inline product-scoped attribute by `title`.
+</Note>
+
+## Body parameters
+
+<ParamField body="title" type="string" required>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, generated from the title if omitted.</ParamField>
+<ParamField body="status" type="string">One of `draft`, `proposed`, `published`, `rejected`.</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="thumbnail" type="string">URL of the product thumbnail.</ParamField>
+<ParamField body="images" type="object[]">
+  Product images.
+  <Expandable title="properties">
+    <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="seller_ids" type="string[]">IDs of sellers eligible to sell the product.</ParamField>
+<ParamField body="categories" type="object[]">
+  Categories to assign the product to.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Category ID.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="tags" type="object[]">
+  Tags to assign to the product.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Tag ID.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="options" type="object[]">
+  Product options used to build variants.
+  <Expandable title="properties">
+    <ParamField body="title" type="string" required>Option title, for example `Size`.</ParamField>
+    <ParamField body="values" type="string[]" required>Possible option values.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="attributes" type="object[]">
+  Unified attribute input — one of two shapes per item.
+  <Expandable title="existing attribute (by id)">
+    <ParamField body="id" type="string" required>ID of an existing catalog attribute.</ParamField>
+    <ParamField body="value_ids" type="string[]">IDs of attribute values to select.</ParamField>
+    <ParamField body="value" type="string | number | boolean">Scalar value for `text`, `unit`, or `toggle` attributes.</ParamField>
+  </Expandable>
+  <Expandable title="inline attribute (by title)">
+    <ParamField body="title" type="string" required>Attribute title.</ParamField>
+    <ParamField body="type" type="string">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ParamField>
+    <ParamField body="values" type="string[]">Value names to create and select.</ParamField>
+    <ParamField body="value" type="string | number | boolean">Scalar value for non-select types.</ParamField>
+    <ParamField body="is_variant_axis" type="boolean">Whether the attribute drives variant generation; only valid for `multi_select`.</ParamField>
+    <ParamField body="is_filterable" type="boolean">Whether the attribute can be used as a storefront filter.</ParamField>
+    <ParamField body="is_required" type="boolean">Whether a value is required on products.</ParamField>
+    <ParamField body="description" type="string">Attribute description.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="variants" type="object[]">
+  Product variants.
+  <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">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="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="options" type="object">Map of option title to option value, for example `{"Size": "M"}`.</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="handle" type="string">Unique URL-safe handle.</ResponseField>
+    <ResponseField name="status" type="string">One of `draft`, `proposed`, `published`, `rejected`.</ResponseField>
+    <ResponseField name="variants" type="object[]">Created 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 with their values.</ResponseField>
+    <ResponseField name="attributes" type="object[]">Computed attribute groups with selected `values` and `all_values`.</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 -X POST 'http://localhost:9000/admin/products' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "title": "Linen Shirt",
+    "seller_ids": ["sel_01HXYZABCDEF"],
+    "options": [{ "title": "Size", "values": ["S", "M"] }],
+    "variants": [
+      { "title": "S", "sku": "LS-S", "options": { "Size": "S" } },
+      { "title": "M", "sku": "LS-M", "options": { "Size": "M" } }
+    ],
+    "attributes": [{ "title": "Material", "type": "single_select", "values": ["Linen"] }]
+  }'
+```
+
+```ts JS Client
+const { product } = await client.admin.products.mutate({
+  title: "Linen Shirt",
+  seller_ids: ["sel_01HXYZABCDEF"],
+  options: [{ title: "Size", values: ["S", "M"] }],
+  variants: [
+    { title: "S", sku: "LS-S", options: { Size: "S" } },
+    { title: "M", sku: "LS-M", options: { Size: "M" } },
+  ],
+  attributes: [{ title: "Material", type: "single_select", values: ["Linen"] }],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "handle": "linen-shirt",
+    "status": "draft",
+    "variants": [
+      { "id": "variant_01HXYZABCDEF", "title": "S", "sku": "LS-S" },
+      { "id": "variant_01HXYZABCDEG", "title": "M", "sku": "LS-M" }
+    ]
+  }
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,48 @@
+---
+title: "Delete Product Variant"
+api: "DELETE /admin/products/{id}/variants/{variant_id}"
+description: "Delete a variant from a product."
+---
+
+Deletes 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>
+
+## Response
+
+<ResponseField name="id" type="string">The deleted variant's ID.</ResponseField>
+<ResponseField name="object" type="string">Always `variant`.</ResponseField>
+<ResponseField name="deleted" type="boolean">Always `true`.</ResponseField>
+<ResponseField name="parent" type="object">The parent product after deletion.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X DELETE 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/variants/variant_01HXYZABCDEF' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const result = await client.admin.products.$id.variants.$variant_id.delete({
+  $id: "prod_01HXYZABCDEF",
+  $variant_id: "variant_01HXYZABCDEF",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "id": "variant_01HXYZABCDEF",
+  "object": "variant",
+  "deleted": true,
+  "parent": {
+    "id": "prod_01HXYZABCDEF",
+    "title": "Linen Shirt",
+    "variants": []
+  }
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,40 @@
+---
+title: "Delete Product"
+api: "DELETE /admin/products/{id}"
+description: "Delete a master catalog product."
+---
+
+Soft-deletes the product and its variants.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Response
+
+<ResponseField name="id" type="string">The deleted product's ID.</ResponseField>
+<ResponseField name="object" type="string">Always `product`.</ResponseField>
+<ResponseField name="deleted" type="boolean">Always `true`.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X DELETE 'http://localhost:9000/admin/products/prod_01HXYZABCDEF' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const result = await client.admin.products.$id.delete({
+  $id: "prod_01HXYZABCDEF",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "id": "prod_01HXYZABCDEF",
+  "object": "product",
+  "deleted": true
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,91 @@
+---
+title: "List Product Variants"
+api: "GET /admin/products/{id}/variants"
+description: "Retrieve a paginated list of a product's variants."
+---
+
+Returns the variants of a single product, with optional filtering by SKU and identifiers.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>The product's ID.</ParamField>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">Maximum number of records to return.</ParamField>
+<ParamField query="offset" type="number" default="0">Number of records to skip.</ParamField>
+<ParamField query="order" type="string">Field to sort by, prefix with `-` for descending order.</ParamField>
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</ParamField>
+<ParamField query="q" type="string">Search term matched against variant fields.</ParamField>
+<ParamField query="id" type="string | string[]">Filter by variant ID(s).</ParamField>
+<ParamField query="sku" type="string">Filter by SKU.</ParamField>
+<ParamField query="ean" type="string">Filter by EAN.</ParamField>
+<ParamField query="upc" type="string">Filter by UPC.</ParamField>
+<ParamField query="barcode" type="string">Filter by barcode.</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">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="hs_code" type="string">Harmonized System code.</ResponseField>
+    <ResponseField name="mid_code" type="string">Manufacturer identification code.</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>
+<ResponseField name="count" type="number">Total number of matching variants.</ResponseField>
+<ResponseField name="offset" type="number">Number of records skipped.</ResponseField>
+<ResponseField name="limit" type="number">Number of records returned.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/products/prod_01HXYZABCDEF/variants?limit=20' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { variants, count } = await client.admin.products.$id.variants.query({
+  $id: "prod_01HXYZABCDEF",
+  limit: 20,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "variants": [
+    {
+      "id": "variant_01HXYZABCDEF",
+      "title": "M",
+      "sku": "LS-M",
+      "product_id": "prod_01HXYZABCDEF",
+      "manage_inventory": false,
+      "allow_backorder": false,
+      "variant_rank": 0
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,109 @@
+---
+title: "List Products"
+api: "GET /admin/products"
+description: "Retrieve a paginated list of master catalog products."
+---
+
+Returns all products across the marketplace, with optional filtering by status, seller, category, and more.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">Maximum number of records to return.</ParamField>
+<ParamField query="offset" type="number" default="0">Number of records to skip.</ParamField>
+<ParamField query="order" type="string">Field to sort by, prefix with `-` for descending order.</ParamField>
+<ParamField query="fields" type="string">Comma-separated list of fields to include, prefix with `+`/`-` to add or remove from defaults.</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="seller_id" type="string | string[]">Filter by the seller(s) eligible to sell the product.</ParamField>
+<ParamField query="status" type="string[]">Filter by status: `draft`, `proposed`, `published`, or `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 that have (or don't have) seller offers.</ParamField>
+<ParamField query="created_at" type="object">Filter by creation date with operators like `$gte`, `$lte`.</ParamField>
+<ParamField query="updated_at" type="object">Filter by update date with operators like `$gte`, `$lte`.</ParamField>
+<ParamField query="deleted_at" type="object">Filter by deletion date with operators like `$gte`, `$lte`.</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">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="external_id" type="string">ID of the product in an external system.</ResponseField>
+    <ResponseField name="collection_id" type="string">ID of the product's collection.</ResponseField>
+    <ResponseField name="type_id" type="string">ID of the product's type.</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, each with its parent `attribute`.</ResponseField>
+    <ResponseField name="scoped_attributes" type="object[]">Product-scoped (inline) attributes with their `values`.</ResponseField>
+    <ResponseField name="attributes" type="object[]">Computed attribute groups, each with the selected `values` and the attribute's full `all_values`.</ResponseField>
+    <ResponseField name="weight" type="number">Product weight.</ResponseField>
+    <ResponseField name="length" type="number">Product length.</ResponseField>
+    <ResponseField name="height" type="number">Product height.</ResponseField>
+    <ResponseField name="width" type="number">Product width.</ResponseField>
+    <ResponseField name="hs_code" type="string">Harmonized System code.</ResponseField>
+    <ResponseField name="mid_code" type="string">Manufacturer identification code.</ResponseField>
+    <ResponseField name="origin_country" type="string">Country of origin.</ResponseField>
+    <ResponseField name="material" type="string">Product material.</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>
+<ResponseField name="count" type="number">Total number of matching products.</ResponseField>
+<ResponseField name="offset" type="number">Number of records skipped.</ResponseField>
+<ResponseField name="limit" type="number">Number of records returned.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/admin/products?status[]=published&limit=20' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { products, count } = await client.admin.products.query({
+  status: ["published"],
+  limit: 20,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "products": [
+    {
+      "id": "prod_01HXYZABCDEF",
+      "title": "Linen Shirt",
+      "handle": "linen-shirt",
+      "status": "published",
+      "thumbnail": "https://cdn.example.com/linen-shirt.png",
+      "variants": [
+        { "id": "variant_01HXYZABCDEF", "title": "M", "sku": "LS-M", "variant_rank": 0 }
+      ],
+      "created_at": "2026-06-01T10:00:00.000Z",
+      "updated_at": "2026-06-01T10:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,78 @@
+---
+title: "Preview Product Changes"
+api: "GET /admin/products/{id}/preview"
+description: "Retrieve the pending change set for a product."
+---
+
+Returns the product's pending change request with its individual change actions, or `null` if no change is pending.
+
+<Note>
+The response contains the pending `product_change` record and its `actions` — the raw edits awaiting review — not a merged product payload.
+</Note>
+
+## 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 product change's ID.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the product the change applies to.</ResponseField>
+    <ResponseField name="status" type="string">Always `pending` for this endpoint.</ResponseField>
+    <ResponseField name="internal_note" type="string">Note visible to operators only.</ResponseField>
+    <ResponseField name="external_note" type="string">Note visible to the vendor.</ResponseField>
+    <ResponseField name="created_by" type="string">ID of the actor who created the change.</ResponseField>
+    <ResponseField name="actions" type="object[]">
+      Individual change actions, in order.
+      <Expandable title="properties">
+        <ResponseField name="id" type="string">The action's ID.</ResponseField>
+        <ResponseField name="action" type="string">The action type.</ResponseField>
+        <ResponseField name="ordering" type="number">Application order of the action.</ResponseField>
+        <ResponseField name="details" type="object">The proposed field changes.</ResponseField>
+        <ResponseField name="applied" type="boolean">Whether the action has been applied.</ResponseField>
+      </Expandable>
+    </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/preview' \
+  -H 'Authorization: Bearer <token>'
+```
+
+```ts JS Client
+const { product_change } = await client.admin.products.$id.preview.query({
+  $id: "prod_01HXYZABCDEF",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_change": {
+    "id": "prodch_01HXYZABCDEF",
+    "product_id": "prod_01HXYZABCDEF",
+    "status": "pending",
+    "internal_note": null,
+    "external_note": null,
+    "actions": [
+      {
+        "id": "prodchact_01HXYZABCDEF",
+        "action": "update_product",
+        "ordering": 0,
+        "details": { "title": "Linen Shirt v2" },
+        "applied": false
+      }
+    ],
+    "created_at": "2026-06-01T10:00:00.000Z",
+    "updated_at": "2026-06-01T10:00:00.000Z"
+  }
+}
+```
+</ResponseExample>