Migrate product clients for FAMILY and response changes

A coordinated Bluestone PIM API release introduces the FAMILY product type and removes three deprecated legacy Sync fields from product responses.

The hierarchy additions are backward-compatible for clients that accept unknown properties and enum values. The field removal can break generated DTOs, strict response schemas, or application code that still expects the removed properties.

Use this guide to review Management API (MAPI) and Public API (PAPI) integrations before adopting an updated API definition.

Changes at a glance

The changes ship together so integrations need one coordinated compatibility review.

Determine whether you need to act

MAPI hierarchy additions

MAPI adds a third hierarchy level:

FAMILY -> GROUP -> VARIANT

The product type enum gains FAMILY. Existing product responses can also contain:

The existing variantParentId and productVariants fields do not change.

These additions affect product detail, list, view, filter, cursor, and connection responses where the new fields apply.

For instructions on creating and managing the hierarchy, see Work with product families, groups, and variants.

Removed MAPI fields

The following legacy Sync fields are removed from product response schemas:

The fields were deprecated and returned null for current integrations. Remove application logic, generated-model overrides, fixtures, and schema requirements that still reference them.

The PublishState enum is no longer referenced by these product responses.

Affected MAPI operations

Any operation that returns one of the affected schemas can change. Review at least:

• GET /pim/products/{id};
• product list and filter operations;
• product view operations, including requests by ID;
• cursor and view-cursor operations; and
• product connection, variant, and group subresources that return ProductConnectionMetadata.

This list is not exhaustive. Use the updated PIM OpenAPI definition to find every operation that returns ProductAll, ProductConnectionMetadata, or ProductMetadataViewDto.

PAPI response changes

PAPI adds the FAMILY value to ProductType and adds two optional product properties:

The fields are absent for SINGLE and VARIANT products and for standalone GROUP products.

FAMILY products appear in PAPI only after they are published. A generated client or strict validator that accepts only the previous product type values can fail as soon as a FAMILY product is published.

Migration procedure

1. Find strict assumptions

Search your integration for:

• closed product type enums;
• required-property lists for product response schemas;
• generated DTOs containing state, contextStates, or dataSynced;
• custom serialization or deserialization logic;
• database mappings and analytics transformations based on the removed fields; and
• fixtures or contract tests that compare complete product response objects.

2. Download the correct OpenAPI definitions

Use the definitions for the environment and documentation version your integration targets. See Environments and Generate SDKs and client code from OpenAPI.

Do not generate a Production client from a Test definition without confirming that the API changes have reached Production.

3. Regenerate typed clients

Regenerate MAPI clients from the updated PIM definition and PAPI clients from the updated Bluestone Public API definition.

Review the generated diff before merging it. Confirm that:

• FAMILY is present in every relevant product type enum;
• groupParentId and productGroups are optional or nullable according to the MAPI schema;
• groups and groupParentId are optional in the PAPI model; and
• state, contextStates, and dataSynced are no longer required or referenced in the affected MAPI models.

4. Update application code

• Remove reads and transformations based on the three legacy Sync fields.
• Add FAMILY handling to switches, match expressions, validators, and user-interface mappings.
• Keep GROUP-to-VARIANT logic unchanged.
• Distinguish MAPI's productGroups from PAPI's groups when mapping between models.
• Treat a missing PAPI groupParentId as not applicable rather than as a malformed response.

5. Run compatibility tests

Test at least the following cases:

1. Deserialize an existing SINGLE product.
2. Deserialize a standalone GROUP with no FAMILY parent.
3. Deserialize a FAMILY with an ordered productGroups list.
4. Deserialize an assigned GROUP with both groupParentId and productVariants.
5. Deserialize a VARIANT and confirm variantParentId behavior is unchanged.
6. Process a product response in which state, contextStates, and dataSynced are absent.
7. Process a PAPI FAMILY response with type set to FAMILY and a groups list.
8. Confirm that complete-object fixtures and schema snapshots do not require the removed fields.

Run these tests against the Test environment before deploying the updated client to Production.

6. Coordinate publication of FAMILY products

Update strict PAPI consumers before publishing FAMILY products. If multiple downstream systems consume PAPI, confirm that each system accepts ProductType=FAMILY before the first FAMILY is published.

Rollout checklist

• Confirm the API change is deployed in the target environment.
• Regenerate strict or generated MAPI and PAPI clients.
• Add FAMILY to product type handling.
• Remove state, contextStates, and dataSynced dependencies.
• Update fixtures, schema snapshots, and database mappings.
• Run MAPI product detail, list, view, cursor, and connection tests.
• Run a PAPI test with a published FAMILY product if your integration consumes PAPI.
• Deploy updated PAPI consumers before publishing FAMILY products in Production.

Related guides

• Work with product families, groups, and variants
• Generate SDKs and client code from OpenAPI
• Deprecated endpoints
• Environments