Work with product families, groups, and variants

Bluestone PIM supports three levels of product variation:

FAMILY -> GROUP -> VARIANT

Use a FAMILY to organize related GROUP products, and use each GROUP to organize its VARIANT products. Existing GROUP-to-VARIANT behavior remains unchanged.

Use the Test environment when you first create or change a product hierarchy.

Product types at a glance

BUNDLE remains a supported product type, but it is not part of the FAMILY-to-GROUP-to-VARIANT hierarchy.

Hierarchy fields

Management API (MAPI) product responses use separate fields for the two relationships:

The new FAMILY fields do not replace or overload the existing variant fields.

A trimmed FAMILY response looks like this:

{
  "id": "family-product-id",
  "name": "Running shoes",
  "number": "RUNNING-SHOES",
  "type": "FAMILY",
  "productGroups": [
    "blue-running-shoes-group-id",
    "red-running-shoes-group-id"
  ]
}

A GROUP can contain both sides of the hierarchy:

{
  "id": "blue-running-shoes-group-id",
  "name": "Blue running shoes",
  "number": "RUNNING-SHOES-BLUE",
  "type": "GROUP",
  "groupParentId": "family-product-id",
  "productVariants": [
    "blue-size-42-variant-id",
    "blue-size-43-variant-id"
  ]
}

The examples are trimmed to highlight the hierarchy fields. Product responses can contain additional product data.

Create a FAMILY

You can create a FAMILY directly or convert an existing SINGLE product.

Create a FAMILY directly

Set type to FAMILY when you create a product:

curl -i -X POST "$BLUESTONE_API_BASE/pim/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Running shoes",
    "number": "RUNNING-SHOES",
    "type": "FAMILY"
  }'

A successful request returns 201 Created. The new product ID is in the resource-id response header.

Creating a product requires ADD access to PRODUCTS.

Convert a SINGLE product to a FAMILY

Call Create variant family with the internal ID of an existing SINGLE product:

curl -i -X POST \
  "$BLUESTONE_API_BASE/pim/products/$FAMILY_PRODUCT_ID/groups" \
  -H "Authorization: Bearer $TOKEN"

A successful request returns 201 Created. The operation can return:

• 400 Bad Request when the request is invalid;
• 404 Not Found when the product does not exist; or
• 409 Conflict when the product's current state conflicts with the conversion.

Converting a product requires UPDATE access to PRODUCTS.

Assign GROUP products to a FAMILY

Use Assign product groups to assign between 1 and 100 existing GROUP products in one request:

curl -i -X POST \
  "$BLUESTONE_API_BASE/pim/products/groups/append/by-ids?forceVla=false" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "familyVariantId": "family-product-id",
    "productIds": [
      "blue-running-shoes-group-id",
      "red-running-shoes-group-id"
    ]
  }'

The familyVariantId property identifies the FAMILY product. productIds contains the GROUP product IDs to assign. Every ID must be unique within the request.

forceVla controls what happens when propagated attributes already have values on a GROUP:

• false keeps existing values and fills only empty values. This is the default.
• true overwrites existing values with values propagated from the FAMILY.

A successful assignment returns 204 No Content. Assigning GROUP products requires UPDATE access to PRODUCTS.

Change GROUP membership and order

Unassign a GROUP

Use Unassign product group from variant family:

curl -i -X DELETE \
  "$BLUESTONE_API_BASE/pim/products/$FAMILY_PRODUCT_ID/groups/$GROUP_PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

A successful request returns 204 No Content. The product remains a GROUP after it is unassigned from the FAMILY.

Reorder a GROUP

Use Update product group order and provide a zero-based position:

curl -i -X PUT \
  "$BLUESTONE_API_BASE/pim/products/$FAMILY_PRODUCT_ID/groups/$GROUP_PRODUCT_ID/order?position=0" \
  -H "Authorization: Bearer $TOKEN"

A successful request returns 200 OK. The new order is reflected in the FAMILY product's productGroups array.

Both operations require UPDATE access to PRODUCTS.

Configure group-level attributes

A FAMILY can propagate selected attributes to its GROUP products. The configuration uses the same flags as variant-level attributes:

If definingAttributes, locked, or mandatory is true, copy must also be true. Otherwise, the update is rejected with 400 Bad Request.

Read the configuration

Use Retrieve group level attribute. Reading the configuration requires DETAILS access to ATTRIBUTES.

curl \
  "$BLUESTONE_API_BASE/pim/products/$FAMILY_PRODUCT_ID/groups/attributes/$ATTRIBUTE_DEFINITION_ID" \
  -H "Authorization: Bearer $TOKEN"

Update the configuration

Use Update group level attribute. Updating the configuration requires UPDATE access to ATTRIBUTES.

curl -i -X PUT \
  "$BLUESTONE_API_BASE/pim/products/$FAMILY_PRODUCT_ID/groups/attributes/$ATTRIBUTE_DEFINITION_ID?forceVla=false" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "copy": true,
    "definingAttributes": true,
    "locked": false,
    "mandatory": true
  }'

A successful update returns 204 No Content.

Read FAMILY and GROUP products

groupParentId and productGroups are included where applicable in product detail, list, view, filter, cursor, and connection responses.

Clients that ignore unknown response properties continue to work when these optional fields are added. Clients that strictly validate schemas or enum values must update before consuming FAMILY products. See Migrate product clients for FAMILY and response changes.

Consume FAMILY products through the Public API

The Public API (PAPI) uses slightly different response field names:

These fields are absent when they do not apply, including for SINGLE and VARIANT products and standalone GROUP products.

PAPI's ProductType enum includes FAMILY. A strict client that does not recognize this value can fail when it receives a published FAMILY product. FAMILY products appear in PAPI responses only after they are published.

Related guides

• Migrate product clients for FAMILY and response changes
• Generate SDKs and client code from OpenAPI
• Authentication
• Environments