> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Product Variant

> 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 theme={null}
  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 theme={null}
  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 theme={null}
  {
    "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>