# 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.                                                                                                                                                                                                                  |
| `measurement`  | `EmbeddedMeasurementResource \| null` | -        | The measurement used to compute per-unit prices for 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. Requires the `medias:read` scope. Returned empty when the scope is missing. |
| `optionValues` | `string[]`                            | -        | A list of `Option Value`, each one representing an option value associated with the variant. Requires the `products:read` scope. Returned empty when the scope is missing.                                                                                                |
| `sku`          | `string`                              | Yes      | A unique identifier for the product variant.                                                                                                                                                                                                                              |

## Response

**201** - Product Variant resource created

| Property        | Type                                  | Required | Description                                                                                                                                                                                                                                                               |
| --------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@context`      | `string \| object`                    | -        |                                                                                                                                                                                                                                                                           |
| `@id`           | `string`                              | Yes      |                                                                                                                                                                                                                                                                           |
| `@type`         | `string`                              | Yes      |                                                                                                                                                                                                                                                                           |
| `barcode`       | `string`                              | Yes      | The barcode, unique UPC, or ISBN number for the product.                                                                                                                                                                                                                  |
| `createdAt`     | `string`                              | -        | The date and time when the resource was created (ISO 8601 format).                                                                                                                                                                                                        |
| `id`            | `string`                              | -        | The resource's unique identifier (UUID).                                                                                                                                                                                                                                  |
| `measurement`   | `EmbeddedMeasurementResource \| null` | -        | The measurement used to compute per-unit prices for the variant.                                                                                                                                                                                                          |
| `medias`        | `array`                               | -        | 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. Requires the `medias:read` scope. Returned empty when the scope is missing. |
| `metafields`    | `array`                               | -        | Metafields owned by this variant. Serialized as IRI strings by default; pass `?expand=metafields` to embed full `MetafieldResource` objects. Requires the `metafields:read` scope. Returned empty when the scope is missing.                                              |
| `optionValues`  | `array`                               | -        | A list of `Option Value`, each one representing an option value associated with the variant. Requires the `products:read` scope. Returned empty when the scope is missing.                                                                                                |
| `product`       | `string \| Product \| null`           | Yes      | The product resource it belongs to. Requires the `products:read` scope. Returned null when the scope is missing.                                                                                                                                                          |
| `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.                                                                           |
| `sku`           | `string`                              | Yes      | A unique identifier for the product variant.                                                                                                                                                                                                                              |
| `updatedAt`     | `string`                              | -        | The date and time when the resource was last modified (ISO 8601 format).                                                                                                                                                                                                  |

## Errors

**400** - Invalid input

| Property      | Type               | Required | Description                                                                                                                          |
| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@context`    | `string \| object` | -        |                                                                                                                                      |
| `@id`         | `string`           | Yes      |                                                                                                                                      |
| `@type`       | `string`           | Yes      |                                                                                                                                      |
| `code`        | `string`           | -        | Stable identifier of the error in the error code catalogue (see /api/error-codes). Present on catalogued errors only.                |
| `description` | `string \| null`   | -        |                                                                                                                                      |
| `detail`      | `string \| null`   | -        | A human-readable explanation specific to this occurrence of the problem.                                                             |
| `instance`    | `string \| null`   | -        | A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. |
| `message`     | `string`           | -        | End-user message localized in the request locale, with this occurrence's values substituted. Present on catalogued errors only.      |
| `slug`        | `string`           | -        | Stable, readable key of the error in the error code catalogue. Present on catalogued errors only.                                    |
| `status`      | `integer \| null`  | -        |                                                                                                                                      |
| `title`       | `string \| null`   | -        | A short, human-readable summary of the problem. For a catalogued error it repeats the `slug`.                                        |
| `type`        | `string`           | -        | A URI reference that identifies the problem type. For a catalogued error it is the error code resource, `/api/error-codes/{code}`.   |

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

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

**422** - An error occurred

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

## 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: unstable' \
  -H 'Accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -d '{
  "barcode": "BAR-001-A",
  "optionValues": [
    "/api/product_options/019af941-6b7c-7d8e-9f0a-2b3c4d5e6f70/option_values/f141d328-9251-5b9c-9de8-c8dce2ac0e49",
    "/api/product_options/019af941-6b7c-7d8e-9f0a-2b3c4d5e6f70/option_values/9e183bb6-27d0-5b74-a20a-ba89391a0689"
  ],
  "sku": "SKU-ABC-001"
}'
```

### Example response

```json
{
  "@context": "/api/contexts/Product%20Variant",
  "@id": "/api/products/019af93e-420e-79f8-800b-6680f03dce20/variants/fdbbd7cd-c638-5360-bdec-fe05344a079b",
  "@type": "Product Variant",
  "barcode": "BAR-001-A",
  "createdAt": "2024-01-01T00:00:00+00:00",
  "id": "fdbbd7cd-c638-5360-bdec-fe05344a079b",
  "measurement": null,
  "medias": [],
  "optionValues": [
    "/api/product_options/019af941-6b7c-7d8e-9f0a-2b3c4d5e6f70/option_values/3b94ebf1-e38d-5745-b38b-5fa73f1e50e3",
    "/api/product_options/019af941-6b7c-7d8e-9f0a-2b3c4d5e6f70/option_values/c1300d1d-8acd-5953-b138-14f15665dc25"
  ],
  "product": "/api/products/019af93e-420e-79f8-800b-6680f03dce20",
  "sku": "SKU-ABC-001",
  "updatedAt": "2024-01-01T00:00:00+00:00"
}
```