Manage Product Hierarchy (BETA)

📘

BETA

The Product Hierarchy services are currently in BETA. These endpoints allow for advanced configuration of product relationships but may change in future updates. We recommend testing these features in a Sandbox environment before production deployment.

While the Product Catalog API defines what products exist (their SKUs, prices, and attributes), the Product Hierarchy API defines how they relate to each other visually and logically in the CPQ interface.

This API allows you to build a nested tree structure of Products, Bundles, and Labels, enabling you to:

• Group products under visual Labels.
• Enforce selection rules (e.g., "Select exactly one option from this group").
• Define mandatory or alternative relationships between items .

The Hierarchy Tree

The hierarchy is structured as a tree of Elements. Each element can contain a list of children, allowing you to nest items up to 10 levels deep.

Each element in the tree has the following properties:

Retrieving the Hierarchy

You can retrieve the current hierarchy tree to visualize the structure or back up the configuration before making changes. Use the Get Product Hierarchy endpoint, informing the version_id

curl --location 'https://api.dealhub.io/api/v1/version/160EDBdA51E28FAA/products_hierarchy' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

The endpoint returns a JSON array representing the root nodes of the tree. Each node contains an element object and a children array .

[
  {
    "element": {
      "type": "PRODUCT",
      "mandatory": false,
      "labelNameOrSku": "Product-A",
      "alternative": false
    },
    "children": []
  },
  {
    "element": {
      "type": "LABEL",
      "mandatory": true,
      "labelNameOrSku": "Required Hardware",
      "alternative": false
    },
    "children": [
      {
        "element": {
          "type": "PRODUCT",
          "mandatory": true,
          "labelNameOrSku": "Hardware-SKU-1",
          "alternative": false
        },
        "children": []
      }
    ]
  }
]

Creating or Replacing the Hierarchy

To define the hierarchy, you must upload the complete tree structure to a Draft version.

❗️

Important: Full Replacement

This operation is destructive. If a hierarchy tree already exists, uploading a new JSON will completely replace the existing tree. The old structure is deleted and replaced with the new payload.

Use the Create or Update Product Hierarchy endpoint. When constructing your tree, ensure that it adheres to the following rules to avoid 400 Bad Request errors:

• Max Depth: You cannot nest items deeper than 10 levels.

• Max Size: The request can contain a maximum of 50,000 elements.

• Label Requirements: If a LABEL is set to mandatory: true, it must contain at least one child that is also mandatory: true.

• Alternative Logic: If an item is set to alternative: true, there must be at least one other alternative item at the same level (creating a choice set).

The following example creates a structure where Product 1 is a standalone item, and Label A contains Product 3.

[
  {
    "element": {
      "type": "PRODUCT",
      "mandatory": false,
      "labelNameOrSku": "Product 1",
      "alternative": false
    },
    "children": []
  },
  {
    "element": {
      "type": "LABEL",
      "mandatory": true,
      "labelNameOrSku": "Label A",
      "alternative": false
    },
    "children": [
      {
        "element": {
          "type": "PRODUCT",
          "mandatory": false,
          "labelNameOrSku": "Product 3",
          "alternative": false
        },
        "children": []
      }
    ]
  }
]

Deleting the Hierarchy

You can remove the entire product hierarchy structure from a version using the Delete from Product Hierarchyendpoint. This does not delete the products from the catalog. It only removes the relationships and visual grouping between them.

🚧

Draft Only

Like other modification endpoints, this can only be triggered on a version in DRAFT status. Attempting to delete the hierarchy of an Active version will fail .

Next Steps

• Updating the Product Catalog: Ensure the SKUs you use in the hierarchy actually exist in the catalog.
• Version API Overview: Review the version lifecycle to manage your Drafts.