Update the Product Catalog

This guide explains how to create, update, or delete products in your DealHub catalog. This is essential for keeping your sales configuration synchronized with external systems like an ERP or PLM.

❗️
Important: Data Safety
The Product Catalog API uses a replacement model. When you upload a product definition, it completely overwrites the existing configuration for that SKU.
If you omit fields (like tags or product_attributes) in your upload, they will be deleted from the system. Always retrieve the full product definition first, modify the necessary fields, and then upload the complete object back .

The Update Workflow

To update products safely, follow this "Get-Modify-Post" cycle:

Retrieve: Fetch the full product definition using GET /version/{version_id}/products_catalog (Get Product Catalog).
Modify: Edit the JSON locally to change attributes, pricing, or rules.
Upload: Push the complete JSON back using POST /version/{version_id}/products_catalog (Create or Update Product Catalog).
Verify: Check the asynchronous request status to ensure success.

Creating or Updating Products

Use the (Create or Update Product Catalog endpoint to upload your changes. This operation is asynchronous.

The payload allows you to define products and bundles. The structure is deep, allowing you to configure everything from basic attributes to complex assignment logic.

{
  "products": [
    {
      "sku": "ABC-123",
      "name": "Enterprise License",
      "description": "Annual subscription",
      "product_assignments": [...],
      "product_pricing": {...}
    }
  ]
}

When constructing your payload, pay attention to these critical objects:

Section	Field Name	Description
Product Pricing	`product_pricing`	Defines how the price is calculated. You must choose between Basic and Advanced modes.
Product Pricing	`price_type`	Determines the source of the price. The options include `SOLID` (fixed price), `ERP` (external price), or `FROM_ALL_QUOTE` (percentage of total quote).
Product Pricing	`pricing_rules`	An ordered list of pricing rules. When in advanced mode, the system evaluates these rules sequentially until a match is found.
Product Assignments	`product_assignments`	Controls when a product is automatically added to a quote.
Product Assignments	`assignment`	Set to `RULE_BASED` to apply logic-driven assignment, or `NEVER` to disable automatic assignment.
Product Assignments	`assignment_rules`	Defines the logic conditions (e.g., `[Region] = "US"`) and the associated `product_factors` (such as Quantity or Duration) applied when a rule matches. Product factors accept either an integer for fixed values or a string in bracket notation when the value is driven by a Playbook question (e.g., `"[general_q.duration_months]"`). See the note below the table for details.

📘
Product Factor Value Types
Product factors such as duration and quantity are multipliers applied to a product's base price during quote generation. In the product catalog payload, they accept two value types:
Integer: Use when the factor is a fixed number that does not change between quotes:
"duration": 12,
"quantity": 1
String: Use when the factor should be driven by a Playbook question or formula. Pass the fully qualified question ID in bracket notation. DealHub resolves the value at quote generation time:
"duration": "[general_q.duration_months]",
"quantity": "[products.qty]"
Always perform a GET on the existing product catalog before sending a POST. If you omit a product factor that is currently configured, DealHub treats it as deleted.

The API returns a request_id immediately.

{
  "request_id": "4D114DAD97"
}

You must poll the Get Asynchronous Request Status endpoint to confirm the upload completed successfully. If there are validation errors (e.g., missing mandatory fields), the status will be failed .

Deleting Products

You can remove products from a Draft version using the Delete APIs.

🚧
Validation Restrictions
You cannot delete a product if it is:

Marked as Mandatory in the hierarchy.

A Parent to other products in the hierarchy.

Set as an Alternative option in the hierarchy.

You must remove these dependencies in the hierarchy before deleting the product .

Delete Specific SKUs

Use the Delete Specific Products by SKU endpoint to remove obsolete items while keeping the rest of the catalog intact. The response will provide a list of all deleted SKUs:

{
  "skus": ["SKU-OLD-1", "SKU-OLD-2"]
}

Delete All Products

Use the Delete All Products from Catalog endpoint with extreme caution. It wipes the entire product catalog and hierarchy tree from the draft version. This is typically used only when pushing a completely new catalog from an upstream system.

Next Steps

Handling Asynchronous Requests: Learn how to track the status of your upload jobs.
Managing Product Hierarchy (BETA): Learn how to structure your products into parent-child relationships.

📘
Related API Reference
The following API Reference pages document the endpoints used in this guide:

Create or Update Product Catalog

Delete All Products from Catalog

Delete Specific Products by SKU