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

# Product Variants: Size, Color, and More

> Add purchasable variants to your products in Synq. Model size, color, or any dimension with per-variant SKUs, barcodes, prices, and attribute values.

A product variant represents a specific, purchasable version of a product. Where a product is the concept — "Merino Wool Sweater" — a variant is the concrete thing a customer actually buys: the small, in red, at \$89.00. Every variant belongs to exactly one parent product and carries its own `sku`, `barcode`, `price`, and `currency`. Variants also link to [attribute values](/guides/attributes) (such as `color: Red` or `size: S`) giving you full flexibility to model any combination of option dimensions your catalog requires.

<Note>
  All requests require the standard headers:
  `Authorization: Bearer <token>`, `X-Tenant-ID`, and `X-Org-ID`.
</Note>

***

## Create a variant

Add a new variant to an existing product. You need the parent product's UUID as a path parameter.

```bash theme={null}
POST /api/v1/pim/products/{product_id}/variants
```

**Path parameters**

<ParamField path="product_id" type="string" required>
  The UUID of the parent product. The product must exist and belong to your tenant.
</ParamField>

**Request body**

<ParamField body="sku" type="string">
  Your internal Stock Keeping Unit identifier. Should be unique within your tenant's catalog.
</ParamField>

<ParamField body="barcode" type="string">
  EAN-13, UPC-A, or any GTIN-style barcode for this variant.
</ParamField>

<ParamField body="price" type="number">
  The selling price for this variant as a decimal number (e.g., `89.99`).
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://api.synq.com/api/v1/pim/products/018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90/variants \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-ID: $TENANT_ID" \
    -H "X-Org-ID: $ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "sku": "MWS-RED-S",
      "barcode": "0012345678905",
      "price": 89.99,
      "currency": "USD"
    }'
  ```

  ```json Request body theme={null}
  {
    "sku": "MWS-RED-S",
    "barcode": "0012345678905",
    "price": 89.99,
    "currency": "USD"
  }
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "id": "029f8d4b-3c4d-5e6f-a1b2-c3d4e5f6a7b8",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "product_id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
  "sku": "MWS-RED-S",
  "barcode": "0012345678905",
  "price": "89.99",
  "currency": "USD",
  "option_values": null,
  "cost_price": null,
  "data_quality_score": null,
  "created_at": "2024-11-15T11:00:00Z",
  "updated_at": "2024-11-15T11:00:00Z"
}
```

<ResponseField name="id" type="string">
  UUID for this variant. Use it to link inventory levels, media, and attribute values.
</ResponseField>

<ResponseField name="product_id" type="string">
  The parent product's UUID, confirming the association.
</ResponseField>

<ResponseField name="price" type="string">
  Returned as a numeric string to preserve decimal precision.
</ResponseField>

<ResponseField name="option_values" type="object | null">
  A JSON object of human-readable option labels (e.g., `{"size": "S", "color": "Red"}`). Populated separately when you assign attribute values to this variant.
</ResponseField>

***

## Modeling multiple variants

To represent a product that comes in three sizes and two colors — six variants total — create each combination as a separate variant record with a distinct SKU.

```json theme={null}
[
  { "sku": "MWS-RED-S",  "price": 89.99, "currency": "USD" },
  { "sku": "MWS-RED-M",  "price": 89.99, "currency": "USD" },
  { "sku": "MWS-RED-L",  "price": 89.99, "currency": "USD" },
  { "sku": "MWS-BLUE-S", "price": 89.99, "currency": "USD" },
  { "sku": "MWS-BLUE-M", "price": 89.99, "currency": "USD" },
  { "sku": "MWS-BLUE-L", "price": 89.99, "currency": "USD" }
]
```

Send one `POST` request per variant. For large catalogs, use the [Bulk Operations](/guides/bulk-operations) workflow to import many variants at once.

<Tip>
  Keep your SKU format consistent across your catalog. A convention like `{PRODUCT_CODE}-{COLOR_CODE}-{SIZE}` makes it easier to filter and manage variants programmatically.
</Tip>

***

## Assigning attribute values to a variant

After creating a variant, you can attach typed attribute values (defined in your [attribute configuration](/guides/attributes)) to describe option dimensions like size or color. The full attribute linkage flow is:

1. Create an attribute (e.g., `name: "Size"`, `type: "TEXT"`).
2. Create an attribute value for that attribute (e.g., `value: "Small"`, `slug: "small"`).
3. Link the attribute value to the variant using the attribute values API, providing the `variant_id` and `attribute_value_id`.

Once linked, the `option_values` field on the variant reflects the resolved label pairs for display purposes.

<Warning>
  Deleting a variant is not exposed through the current API surface. To retire a variant, set its inventory levels to zero and stop referencing it in new orders.
</Warning>