@mercurjs/docs 2.2.0-canary.40

package/content/references/api/vendor/payouts/retrieve-payout.mdx

@@ -0,0 +1,63 @@
+---
+title: "Retrieve Payout"
+api: "GET /vendor/payouts/{id}"
+description: "Retrieve one of the seller's payouts by ID."
+---
+
+Returns a payout, verifying it belongs to the current seller.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The payout's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response.
+</ParamField>
+
+## Response
+
+<ResponseField name="payout" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The payout's ID.</ResponseField>
+    <ResponseField name="display_id" type="number">Human-readable payout number.</ResponseField>
+    <ResponseField name="amount" type="number">The payout amount.</ResponseField>
+    <ResponseField name="currency_code" type="string">The payout currency.</ResponseField>
+    <ResponseField name="status" type="enum">One of `pending`, `processing`, `paid`, `failed`, `canceled`.</ResponseField>
+    <ResponseField name="data" type="object">Provider-specific data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/payouts/pout_01HXYZ' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { payout } = await client.vendor.payouts.$id.query({
+  $id: "pout_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "payout": {
+    "id": "pout_01HXYZ",
+    "display_id": 42,
+    "amount": 1250,
+    "currency_code": "usd",
+    "status": "paid",
+    "created_at": "2026-01-15T10:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/product-attributes/list-product-attributes.mdx

@@ -0,0 +1,135 @@
+---
+title: "List Product Attributes"
+api: "GET /vendor/product-attributes"
+description: "Retrieve a paginated list of global product attributes."
+---
+
+Returns global attribute definitions (product-scoped attributes are excluded) with their values and category assignments.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  The maximum number of attributes to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  The number of attributes to skip before returning results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  The field to sort by, e.g. `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 attribute fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by attribute ID(s).
+</ParamField>
+
+<ParamField query="handle" type="string | string[]">
+  Filter by attribute handle(s).
+</ParamField>
+
+<ParamField query="type" type="string | string[]">
+  Filter by type. Values: `single_select`, `multi_select`, `unit`, `toggle`, `text`.
+</ParamField>
+
+<ParamField query="is_required" type="boolean">
+  Filter by whether the attribute is required.
+</ParamField>
+
+<ParamField query="is_variant_axis" type="boolean">
+  Filter by whether the attribute drives variant combinations.
+</ParamField>
+
+<ParamField query="is_filterable" type="boolean">
+  Filter by whether the attribute is filterable.
+</ParamField>
+
+<ParamField query="is_active" type="boolean">
+  Filter by whether the attribute is active.
+</ParamField>
+
+<ParamField query="category_id" type="string | string[]">
+  Filter by assigned category ID(s).
+</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="product_attributes" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The attribute's ID.</ResponseField>
+    <ResponseField name="name" type="string">The attribute's name.</ResponseField>
+    <ResponseField name="handle" type="string">The attribute's handle.</ResponseField>
+    <ResponseField name="description" type="string">The attribute's description.</ResponseField>
+    <ResponseField name="type" type="string">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ResponseField>
+    <ResponseField name="is_required" type="boolean">Whether a value is required on products.</ResponseField>
+    <ResponseField name="is_filterable" type="boolean">Whether the attribute can be used for filtering.</ResponseField>
+    <ResponseField name="is_variant_axis" type="boolean">Whether the attribute drives variant combinations.</ResponseField>
+    <ResponseField name="is_active" type="boolean">Whether the attribute is active.</ResponseField>
+    <ResponseField name="rank" type="number">Sort rank of the attribute.</ResponseField>
+    <ResponseField name="values" type="object[]">The attribute's values with `id`, `name`, `handle`, and `rank`.</ResponseField>
+    <ResponseField name="categories" type="object[]">Assigned categories with `id`, `name`, and `handle`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching attributes.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped attributes.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned attributes.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/product-attributes?type=multi_select' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { product_attributes, count } =
+  await client.vendor.productAttributes.query({ type: "multi_select" })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_attributes": [
+    {
+      "id": "pattr_01HXYZ",
+      "name": "Color",
+      "handle": "color",
+      "type": "multi_select",
+      "is_variant_axis": true,
+      "values": [
+        { "id": "pattrval_01HXYZ", "name": "Red", "rank": 0 }
+      ]
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+</ResponseExample>

package/content/references/api/vendor/product-attributes/retrieve-product-attribute.mdx

@@ -0,0 +1,71 @@
+---
+title: "Retrieve Product Attribute"
+api: "GET /vendor/product-attributes/{id}"
+description: "Retrieve a product attribute by its ID."
+---
+
+Returns a single attribute definition with its values and category assignments.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The attribute's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response. Prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_attribute" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The attribute's ID.</ResponseField>
+    <ResponseField name="name" type="string">The attribute's name.</ResponseField>
+    <ResponseField name="handle" type="string">The attribute's handle.</ResponseField>
+    <ResponseField name="description" type="string">The attribute's description.</ResponseField>
+    <ResponseField name="type" type="string">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ResponseField>
+    <ResponseField name="is_required" type="boolean">Whether a value is required on products.</ResponseField>
+    <ResponseField name="is_filterable" type="boolean">Whether the attribute can be used for filtering.</ResponseField>
+    <ResponseField name="is_variant_axis" type="boolean">Whether the attribute drives variant combinations.</ResponseField>
+    <ResponseField name="is_active" type="boolean">Whether the attribute is active.</ResponseField>
+    <ResponseField name="rank" type="number">Sort rank of the attribute.</ResponseField>
+    <ResponseField name="metadata" type="object">Custom key-value pairs.</ResponseField>
+    <ResponseField name="values" type="object[]">The attribute's values with `id`, `name`, `handle`, and `rank`.</ResponseField>
+    <ResponseField name="categories" type="object[]">Assigned categories with `id`, `name`, and `handle`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/vendor/product-attributes/pattr_01HXYZ' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { product_attribute } = await client.vendor.productAttributes.$id.query({
+  $id: "pattr_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_attribute": {
+    "id": "pattr_01HXYZ",
+    "name": "Color",
+    "handle": "color",
+    "type": "multi_select",
+    "is_variant_axis": true,
+    "values": [
+      { "id": "pattrval_01HXYZ", "name": "Red", "rank": 0 },
+      { "id": "pattrval_01HABC", "name": "Blue", "rank": 1 }
+    ]
+  }
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,136 @@
+---
+title: "List Variants"
+api: "GET /vendor/product-variants"
+description: "Retrieve a paginated list of product variants across products."
+---
+
+Returns product variants regardless of parent product, with the parent product embedded.
+
+## 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. `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.
+</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="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="sku" type="string | string[]">
+  Filter by SKU(s).
+</ParamField>
+
+<ParamField query="ean" type="string | string[]">
+  Filter by EAN(s).
+</ParamField>
+
+<ParamField query="upc" type="string | string[]">
+  Filter by UPC(s).
+</ParamField>
+
+<ParamField query="barcode" type="string | string[]">
+  Filter by barcode(s).
+</ParamField>
+
+<ParamField query="product_id" type="string | string[]">
+  Filter by parent product ID(s).
+</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="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="ean" type="string">EAN barcode.</ResponseField>
+    <ResponseField name="upc" type="string">UPC barcode.</ResponseField>
+    <ResponseField name="barcode" type="string">Generic barcode.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the parent product.</ResponseField>
+    <ResponseField name="product" type="object">The parent product record.</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>
+  </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/product-variants?sku=ACME-SHIRT-M' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { variants, count } = await client.vendor.productVariants.query({
+  sku: "ACME-SHIRT-M",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "variants": [
+    {
+      "id": "variant_01HXYZ",
+      "title": "M",
+      "sku": "ACME-SHIRT-M",
+      "product_id": "prod_01HXYZ",
+      "product": { "id": "prod_01HXYZ", "title": "Acme T-Shirt" }
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/batch-product-attributes.mdx

@@ -0,0 +1,104 @@
+---
+title: "Batch Product Attributes"
+api: "POST /vendor/products/{id}/attributes/batch"
+description: "Stage attribute additions, removals, and updates on a product."
+---
+
+Stages attribute operations as a pending change request instead of applying them directly.
+
+<Note>
+  The endpoint responds with `202 Accepted` and a `product_change` record containing `ATTRIBUTE_ADD` / `ATTRIBUTE_REMOVE` / `ATTRIBUTE_UPDATE` actions.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="add" type="object[]">
+  Attributes to attach; 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`. Required for inline non-axis attributes unless `value` is a boolean.</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; only allowed on `multi_select` attributes.</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="remove" type="string[]">
+  IDs of attributes to detach from the product.
+</ParamField>
+
+<ParamField body="update" type="object[]">
+  Changes to attributes already attached to the product.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>The attribute's ID.</ParamField>
+    <ParamField body="title" type="string">New attribute title.</ParamField>
+    <ParamField body="add" type="(string | object)[]">Values to select — plain strings or `{ "value": "..." }` objects.</ParamField>
+    <ParamField body="remove" type="string[]">Value IDs to deselect.</ParamField>
+    <ParamField body="value" type="string | number | boolean">New scalar value for `text`, `unit`, or `toggle` attributes.</ParamField>
+  </Expandable>
+</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 attribute operations, each with `id`, `action`, `details`, `ordering`, and `applied`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/products/prod_01HXYZ/attributes/batch' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "add": [{ "id": "pattr_01HXYZ", "value_ids": ["pattrval_01HXYZ"] }],
+    "remove": ["pattr_01HABC"]
+  }'
+```
+
+```ts JS Client
+const { product_change } =
+  await client.vendor.products.$id.attributes.batch.mutate({
+    $id: "prod_01HXYZ",
+    add: [{ id: "pattr_01HXYZ", value_ids: ["pattrval_01HXYZ"] }],
+    remove: ["pattr_01HABC"],
+  })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 202
+{
+  "product_change": {
+    "id": "prodch_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "status": "pending",
+    "actions": [
+      {
+        "id": "prodchact_01HXYZ",
+        "action": "ATTRIBUTE_ADD",
+        "details": { "id": "pattr_01HXYZ", "value_ids": ["pattrval_01HXYZ"] },
+        "applied": false
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/products/cancel-product-change.mdx

@@ -0,0 +1,62 @@
+---
+title: "Cancel Product Change"
+api: "POST /vendor/products/{id}/cancel"
+description: "Cancel the seller's pending change request for a product."
+---
+
+Cancels the product's pending change request; responds `404` when no pending change exists.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="internal_note" type="string">
+  Optional note recorded with the cancellation.
+</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 targeted.</ResponseField>
+    <ResponseField name="status" type="string">`canceled` after this call.</ResponseField>
+    <ResponseField name="canceled_by" type="string">ID of the seller that canceled the change.</ResponseField>
+    <ResponseField name="canceled_at" type="string">Timestamp of the cancellation.</ResponseField>
+    <ResponseField name="actions" type="object[]">The staged operations that were discarded.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/products/prod_01HXYZ/cancel' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+```ts JS Client
+const { product_change } = await client.vendor.products.$id.cancel.mutate({
+  $id: "prod_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_change": {
+    "id": "prodch_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "status": "canceled",
+    "canceled_by": "sel_01HXYZ",
+    "canceled_at": "2026-07-03T12:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,92 @@
+---
+title: "Create Product Variant"
+api: "POST /vendor/products/{id}/variants"
+description: "Stage the addition of a variant to a product."
+---
+
+Stages a `VARIANT_ADD` operation as a pending change request instead of creating the variant directly.
+
+<Note>
+  The endpoint responds with `202 Accepted` and a `product_change` record; the variant appears on the product once the change is confirmed. The staged variant is always created with `manage_inventory: false` — stock is tracked on offers.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The product's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="title" type="string" required>The variant's title.</ParamField>
+<ParamField body="sku" type="string">The variant's 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="allow_backorder" type="boolean">Whether backorders are allowed.</ParamField>
+<ParamField body="manage_inventory" type="boolean">Accepted in the body but forced to `false` when the change is staged.</ParamField>
+<ParamField body="thumbnail" type="string">Variant thumbnail URL.</ParamField>
+<ParamField body="metadata" type="object">Custom key-value pairs.</ParamField>
+<ParamField body="options" type="object">Option title to value mapping, e.g. `{"Size": "L"}`.</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_ADD`), `details`, `ordering`, and `applied`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/products/prod_01HXYZ/variants' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{"title": "L", "sku": "ACME-SHIRT-L", "options": {"Size": "L"}}'
+```
+
+```ts JS Client
+const { product_change } = await client.vendor.products.$id.variants.mutate({
+  $id: "prod_01HXYZ",
+  title: "L",
+  sku: "ACME-SHIRT-L",
+  options: { Size: "L" },
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 202
+{
+  "product_change": {
+    "id": "prodch_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "status": "pending",
+    "actions": [
+      {
+        "id": "prodchact_01HXYZ",
+        "action": "VARIANT_ADD",
+        "details": { "title": "L", "sku": "ACME-SHIRT-L" },
+        "applied": false
+      }
+    ]
+  }
+}
+```
+</ResponseExample>