# Create a variant

> Add a variant to a product.

`POST /rest/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.

## Headers

| Name                         | Type     | Required | Description                                                                                                                                      |
| ---------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Flowkiwi-Organization-Id` | `string` | Yes      | The organization the request acts as. Determines the identity, permissions and ownership applied when reading or modifying data on the instance. |

## 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`       | `Media[]`                             | -        | 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`   | `number \| 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                                                                                     |

**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`         | -        |             |
| `type`       | `string`         | -        |             |
| `title`      | `string \| null` | -        |             |
| `instance`   | `string \| null` | -        |             |

## Examples

### Example request

```bash
curl -X POST 'https://<tenant>.product-management.flowkiwi.net/rest/api/products/<product_id>/variants' \
  -H 'Authorization: Bearer {token}' \
  -H 'X-Flowkiwi-Organization-Id: <org_id>' \
  -H 'Accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -d '{
  "barcode": "BAR-001-A",
  "sku": "SKU-ABC-001",
  "optionValues": [
    "/rest/api/optionValues/f2ddb865-ba60-588d-afd6-588814d46b73",
    "/rest/api/optionValues/b0794cb4-f72d-55ba-a28b-2ee81d92fbda"
  ]
}'
```

### Example response

```json
{
  "@context": "/rest/api/contexts/Variant",
  "@id": "/rest/api/Variants/02a1327c-961e-5492-9169-05751ff97830",
  "@type": "Variant",
  "id": "02a1327c-961e-5492-9169-05751ff97830",
  "barcode": "BAR-001-A",
  "sku": "SKU-ABC-001",
  "measurement": null,
  "product": "/rest/api/products/b4006464-4a28-5537-9428-a5228fac095b",
  "optionValues": [
    "/rest/api/optionValues/cc39274b-cacc-5242-ad1c-2e331999f28e",
    "/rest/api/optionValues/1e23fbeb-531c-5810-b2e7-e20bc1fa2ba6"
  ],
  "images": [],
  "createdAt": "2024-01-01T00:00:00+00:00",
  "updatedAt": "2024-01-01T00:00:00+00:00"
}
```