# Create a variant

> Add a variant to a product.
{/* generated:versioned-pages - edit _pm-authored, not this file */}

`POST /api/products/{productId}/variants`

Creates a Product Variant resource.

Creates a new variant on the given product. Identify the variant by the [Option Values](/api/product-management/option-values/) it combines (for example *Size: M* and *Color: Red*) and give it its own `sku`, `barcode` and `measurement`.

> **Option values**
>
> `optionValues` references existing option values by IRI. The combination must be unique within the product - creating a second variant with the same option values returns a validation error.

## Path parameters

| Name        | Type     | Required | Description                |
| ----------- | -------- | -------- | -------------------------- |
| `productId` | `string` | Yes      | ProductResource identifier |

## Request body

| Property       | Type                                  | Required | Description                                                                                                                                                                                   |
| -------------- | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `barcode`      | `string`                              | Yes      | The barcode, unique UPC, or ISBN number for the product.                                                                                                                                      |
| `sku`          | `string`                              | Yes      | A unique identifier for the product variant.                                                                                                                                                  |
| `measurement`  | `EmbeddedMeasurementResource \| null` | -        | The measurement used to compute per-unit prices for the variant.                                                                                                                              |
| `optionValues` | `string[]`                            | -        | A list of `Option Value`, each one representing an option value associated with the variant.                                                                                                  |
| `medias`       | `string[]`                            | -        | A list of `Media`, ordered by position. Only media of type "image" can be associated with a variant. Returned as IRI strings by default; pass `?expand=medias` to embed full `Media` objects. |

## Response

**201** - Product Variant resource created

| Property        | Type                                  | Required | Description                                                                                                                                                                                     |
| --------------- | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@context`      | `object`                              | -        |                                                                                                                                                                                                 |
| `@id`           | `string`                              | Yes      |                                                                                                                                                                                                 |
| `@type`         | `string`                              | Yes      |                                                                                                                                                                                                 |
| `id`            | `string`                              | -        | The resource's unique identifier (UUID).                                                                                                                                                        |
| `barcode`       | `string`                              | Yes      | The barcode, unique UPC, or ISBN number for the product.                                                                                                                                        |
| `sku`           | `string`                              | Yes      | A unique identifier for the product variant.                                                                                                                                                    |
| `measurement`   | `EmbeddedMeasurementResource \| null` | -        | The measurement used to compute per-unit prices for the variant.                                                                                                                                |
| `product`       | `string`                              | Yes      | The product resource it belongs to.                                                                                                                                                             |
| `optionValues`  | `string[]`                            | -        | A list of `Option Value`, each one representing an option value associated with the variant.                                                                                                    |
| `medias`        | `string[]`                            | -        | A list of `Media`, ordered by position. Only media of type "image" can be associated with a variant. Returned as IRI strings by default; pass `?expand=medias` to embed full `Media` objects.   |
| `resolvedPrice` | `ResolvedPriceResource \| null`       | -        | The price resolved for the current `resolveContext` (country, channel and instant). Null unless `resolveContext[country]`, `resolveContext[channel]` and `resolveContext[at]` are all provided. |
| `metafields`    | `string[]`                            | -        | Metafields owned by this variant. Serialized as IRI strings by default; pass `?expand=metafields` to embed full `MetafieldResource` objects.                                                    |
| `createdAt`     | `string`                              | -        | The date and time when the resource was created (ISO 8601 format).                                                                                                                              |
| `updatedAt`     | `string`                              | -        | The date and time when the resource was last modified (ISO 8601 format).                                                                                                                        |

## Errors

**400** - Invalid input

| Property      | Type              | Required | Description                                                                                                                          |
| ------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@context`    | `object`          | -        |                                                                                                                                      |
| `@id`         | `string`          | Yes      |                                                                                                                                      |
| `@type`       | `string`          | Yes      |                                                                                                                                      |
| `title`       | `string \| null`  | -        | A short, human-readable summary of the problem.                                                                                      |
| `detail`      | `string \| null`  | -        | A human-readable explanation specific to this occurrence of the problem.                                                             |
| `status`      | `integer \| null` | -        |                                                                                                                                      |
| `instance`    | `string \| null`  | -        | A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. |
| `type`        | `string`          | -        | A URI reference that identifies the problem type                                                                                     |
| `description` | `string \| null`  | -        |                                                                                                                                      |

**403** - Access denied. The caller is missing one or more identity permissions required for this operation.

| Property             | Type       | Required | Description                                                                                                                                |
| -------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `@context`           | `object`   | -        |                                                                                                                                            |
| `@id`                | `string`   | Yes      |                                                                                                                                            |
| `@type`              | `string`   | Yes      |                                                                                                                                            |
| `type`               | `string`   | -        |                                                                                                                                            |
| `title`              | `string`   | -        |                                                                                                                                            |
| `status`             | `integer`  | -        |                                                                                                                                            |
| `detail`             | `string`   | -        |                                                                                                                                            |
| `missingPermissions` | `string[]` | -        | Identity permissions that the caller is missing for this operation. Present only when the 403 is caused by a denied identity:* permission. |

**422** - An error occurred

| Property      | Type             | Required | Description |
| ------------- | ---------------- | -------- | ----------- |
| `@context`    | `object`         | -        |             |
| `@id`         | `string`         | Yes      |             |
| `@type`       | `string`         | Yes      |             |
| `status`      | `integer`        | -        |             |
| `violations`  | `object[]`       | -        |             |
| `detail`      | `string`         | -        |             |
| `description` | `string`         | -        |             |
| `type`        | `string`         | -        |             |
| `title`       | `string \| null` | -        |             |
| `instance`    | `string \| null` | -        |             |

## Examples

### Example request

```bash
curl -X POST 'https://<tenant>.product-management.flowkiwi.net/api/products/<product_id>/variants' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Flowkiwi-Api-Version: 2026-07' \
  -H 'Accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -d '{
  "barcode": "BAR-001-A",
  "sku": "SKU-ABC-001",
  "optionValues": [
    "/api/optionValues/f141d328-9251-5b9c-9de8-c8dce2ac0e49",
    "/api/optionValues/9e183bb6-27d0-5b74-a20a-ba89391a0689"
  ]
}'
```

### Example response

```json
{
  "@context": "/api/contexts/Variant",
  "@id": "/api/Variants/fdbbd7cd-c638-5360-bdec-fe05344a079b",
  "@type": "Variant",
  "id": "fdbbd7cd-c638-5360-bdec-fe05344a079b",
  "barcode": "BAR-001-A",
  "sku": "SKU-ABC-001",
  "measurement": null,
  "product": "/api/products/3b94ebf1-e38d-5745-b38b-5fa73f1e50e3",
  "optionValues": [
    "/api/optionValues/c1300d1d-8acd-5953-b138-14f15665dc25",
    "/api/optionValues/6003f215-c814-593d-a67b-8c67f4ec5590"
  ],
  "images": [],
  "createdAt": "2024-01-01T00:00:00+00:00",
  "updatedAt": "2024-01-01T00:00:00+00:00"
}
```