Guides

Update the Product Catalog

Suggest Edits

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:

  1. Retrieve: Fetch the full product definition using GET /version/{version_id}/products_catalog (Get Product Catalog).
  2. Modify: Edit the JSON locally to change attributes, pricing, or rules.
  3. Upload: Push the complete JSON back using POST /version/{version_id}/products_catalog (Create or Update Product Catalog).
  4. 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:

SectionField NameDescription
Product Pricingproduct_pricingDefines how the price is calculated. You must choose between Basic and Advanced modes.
Product Pricingprice_typeDetermines the source of the price. The options include SOLID (fixed price), ERP (external price), or FROM_ALL_QUOTE (percentage of total quote).
Product Pricingpricing_rulesAn ordered list of pricing rules. When in advanced mode, the system evaluates these rules sequentially until a match is found.
Product Assignmentsproduct_assignmentsControls when a product is automatically added to a quote.
Product AssignmentsassignmentSet to RULE_BASED to apply logic-driven assignment, or NEVER to disable automatic assignment.
Product Assignmentsassignment_rulesDefines the logic conditions (e.g., [Region] = "US") and the associated product_factors (such as Quantity or Duration) applied when a rule matches.

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

Updated 18 days ago