---
title: "Product Grouping"
canonical: "https://red-ant-documentation.refined.site/space/RDD/715194369/Product%20Grouping"
format: markdown
---
![image](media://6ce9598e-4d0e-494a-9c70-840ed18903db)

## Overview

Product Groups allows RetailOS to present related products (e.g. shades of makeup, or colour of shoes) together.

## Key Product Fields

These fields control functionality related to product grouping within RetailOS. For full the full product schema, refer to our [Swagger API documentation](https://digital-store-api-qa.herokuapp.com/v2/docs/#/Products/get_products).

| **Parameter** | **Required** | **Data type** | **Description** | **Example** |
| --- | --- | --- | --- | --- |
| `productGroup` | `optional` | `string` | The product group identifier | `51859` |
| `order` | `optional` | `number` | Determines the order in which products and / or product groups are displayed on the PLP | `1` |
| `name` | `required` | `string` | Product name | `LUXURY NAIL POLISH RED` |
| `details.productGroupName` | `optional` | `string` | The product group name | `LUXURY NAIL POLISH` |
| `details.productGroupOrder` | `optional`<br>Default: 0 | `number` | Determines the order in which product options are displayed either within a dropdown or as colour swatches | `4` |
| `details.productGroupShortName` | `optional` | `string` | - Short name for display in dropdowns
- If undefined, RetailOS will display `name` | `RED` |
| `details.swatchImage` | `optional` | `string` | - HTTPS Link to the colour Swatch for the product option
- In the case of both `swatchHexCode` and `swatchImage` being provided, `swatchImage` will take precedence | `"http://example.com/some-swatch-image.jpg"` |
| `details.swatchHexCode` | `optional` | `string` | - Hexadecimal colour of the swatch, as an alternative to imagery
- In the case of both `swatchHexCode` and `swatchImage` being provided, `swatchImage` will take precedence | `#D93931` |

### Other Potential Fields

Below are some other fields that may be relevant depending on client requirements.

| **Parameter** | **Required** | **Data type** | **Description** | **Example** |
| --- | --- | --- | --- | --- |
| `details.productGroupPrimaryProduct` | `optional` | `boolean` | The ‘hero’ product representing the product group on the PLP - this is only relevant if not all products are displayed on the PLP and are instead ‘nested’ within a group | `TRUE` |
| `details.displayType` | `optional` | `enum` | Determines whether colour swatches or a dropdown are displayed for product options, values are either:<br>- swatch (for colour swatch)
- dropdown | `swatch` |

## Product Payload

Example API payload:

```
{
  "transactional": true,
  "rows": [
    {
      "externalProductId": "5185951",
      "name": "LUXURY NAIL POLISH RED",
      "catalogue": "BRANDNAME_EN",
      "brand": "BRANDNAME",
      "link": "http://example.com/your-product-id",
      "service": false,
      "price": {
        "code": "GBP",
        "value": "10.00"
      },
      "discount": {
        "code": "GBP",
        "value": "3"
      },
      "preview": false,
      "images": [
        "http://example.com/some-image.jpg"
      ],
      "regionId": "b529613e-221c-48f1-b7db-3c1720e79879",
      "categoryId": "792c97ed-50d6-4615-9b8e-ca264212a5c5",
      "details": {
        "productGroupName": "LUXURY NAIL POLISH",
        "productGroupShortName": "Red",
        "productGroupOrder": 1,
        "productGroupPrimaryProduct": true,
        "swatchImage": "http://example.com/some-swatch-image.jpg",
        "swatchHexCode": "#D93931",
        "displayType": "swatch"
      },
      "vatPercent": 22.25,
      "productGroup": "51859",
      "order": 1,
      "updateSource": "ClientName"
    }
  ]
}
```

### Variant

No changes to the existing variant process

| **Parameter** | **Required** | **Data type** | **Description** | **Example** |
| --- | --- | --- | --- | --- |
| `name` | `required` | `string` | Variant name | `10ml` |
| `productId` | `required` | `string` | Corresponds to `product`.`externalProductId` | `5185951` |

### Variant Payload

Example API payload:

```
{
  "transactional": true,
  "rows": [
    {
      "name": "10ml",
      "variantOrder": 0,
      "ean": "000123456789",
      "onlineStock": "available",
      "catalogue": "Default",
      "link": "http://example.com/your-variant-id",
      "productId": "5185951",
      "regionId": "b529613e-221c-48f1-b7db-3c1720e79879",
      "details": {},
      "externalVariantId": "product-1-variant-l",
      "updateSource": "ClientName"
    }
  ]
}
```