Understanding mandatory attributes

The Product Catalog API validates variant data based on the feed configuration and validation rules.

The required and available attributes depend on whether the feed is enrich-ready or non-enrich-ready.

Feed types

Mandatory attributes

Which attributes are mandatory is defined per catalog. The API reference describes how a request is built and lists the predefined attributes with their data types. It does not show the attribute set configured for your catalog, and that configuration is what validation runs against.

Note

Query the attributes of your catalog before you build an integration, and again after a release that changes attributes. The request examples in the API reference are illustrations, not a description of your catalog.

Check the attributes of your catalog

Call the catalog metadata endpoint with the ID of the catalog you are writing to:

GET /api/product-catalog/v1/catalogs/metadata/attribute/{catalogId}

The response lists the attributes of that catalog with their names and data types. Use these names in your payloads.

For the full request and response definition, see Get all attributes assigned to a catalog.

How mandatory validation works

A mandatory attribute does not need to be included in every API request.

Mandatory means that the attribute must exist in the final stored variant state.

The variant_id attribute must always be provided in every imported event or request.

Example: Request fails

The following request fails because the variant does not yet exist and the mandatory attributes are missing.

{
  "variant_id": "123",
  "product_description": "this is my description"
}

The request fails because the required mandatory attributes are not yet stored for the variant.

Example: Request succeeds

The following variant already exists with all mandatory attributes.

{
  "variant_id": "123",
  "product_id": "fdasfsa",
  "product_title": "this is my title"
}

The client sends a partial update request.

{
  "variant_id": "123",
  "product_description": "this is my description"
}

This request succeeds because the variant already exists and already contains all mandatory attributes.

When validation rejects a variant

If a mandatory attribute is missing, the response rejects the variant and names the attributes it expected in missingMandatoryFields.

Compare those names against the attribute list returned by the catalog metadata endpoint. A name in missingMandatoryFields that you do not recognize means your payload uses a different name for that attribute.

Related information

Review the validation and feedback documentation for more information about request validation and processing behavior.