Patching Product Catalog Items

This guide explains how to use the PATCH endpoint to update specific data elements for existing products and bundles in your DealHub catalog, without replacing the entire product definition.

Choose the Right Endpoint

The Version API provides two endpoints for modifying the product catalog at the same URL, each designed for a different purpose:

	POST — Create or Update	PATCH — Update Items
Purpose	Upload a full product definition (create new or fully replace existing)	Update specific data elements of existing SKUs
Scope	Entire product object, including identity fields	Data elements only: attributes, assignments, pricing, bundle items
If SKU exists	Completely replaces the existing definition	Merges or replaces only the specified data categories
If SKU does not exist	Creates the product	Fails — the SKU must already exist in the catalog
Fields like `name`, `tags`, `description`	Required and writable	Not writable — changes to identity fields must go through POST

Use PATCH when you need to push targeted changes to data elements, for example, updating prices or assignment rules, without touching the rest of the product definition. Use POST when you need to create products or change identity-level fields.

❗️
DRAFT Versions Only
Like the POST endpoint, PATCH only works against DRAFT versions. Requests targeting ACTIVE or DEACTIVATED versions will fail with a 400 error.

The Two Update Modes

The mode query parameter is mandatory and controls how the provided data interacts with the existing catalog data.

UPDATE Mode

Only the data elements explicitly included in the request are added or updated. Any existing data not referenced in the request remains unchanged.

Example: A product currently has 5 pricing rules: A, B, C, D, E. Your PATCH request includes definitions for rules C and F.

Rule C is replaced with the new definition.
Rule F is created as a new rule.
Rules A, B, D, E are untouched.
Result: the product ends up with 6 pricing rules: A, B, C (updated), D, E, F (new).

Use UPDATE mode for incremental changes, adding new rules or correcting specific entries, when you want to preserve everything else.

REPLACE Mode

Each data category included in the request completely replaces the corresponding data for that SKU. Entries within an included category that are not present in the request are removed. Data categories not referenced at all in the request are left untouched.

Example: The same product has 5 pricing rules: A, B, C, D, E. Your PATCH request includes definitions for rules C and F.

Rules A, B, D, E are removed.
Rule C is replaced with the new definition.
Rule F is created as a new rule.
Result: the product ends up with 2 pricing rules: C (updated), F (new).

📘
Category-Level Scope
REPLACE mode operates at the data category level, not at the product level. If your request body includes product_pricing but omits product_assignments, only the pricing rules are replaced, the assignment rules remain exactly as they were.

Use REPLACE mode when you want a clean slate for a specific data category, such as completely redefining all assignment rules for a set of SKUs.

What You Can Update

The following data categories can be included in a PATCH request body:

Data Category	Applies To	Description
`product_attributes`	Products, Bundles	Key-value attribute map. Attribute names must be pre-declared in the CPQ version.
`product_assignments`	Products, Bundles	Assignment rules that control when a product is automatically added to a quote.
`product_pricing`	Products, Bundles	Pricing rules, including price type, formula, discounts, and currency handling.
`bundle_items`	Bundles only	The list of products included within the bundle.

Identity fields (name, description, tags, primary_tag, merge_products, product_conditional_names, and bundle-level fields like bundle_type) cannot be modified via PATCH. To change these, use the POST endpoint.

Make a PATCH Request

Send a PATCH request to the /api/v1/version/{version_id}/products_catalog?mode={UPDATE|REPLACE} endpoint, with the mode query parameter. The request body contains a products array, a bundles array, or both. You only need to include the SKUs and data categories you want to update:

{
  "products": [
    {
      "sku": "ABC-12345-S-BL",
      "product_attributes": {
        "Department": { "value": "1022" },
        "Model": { "value": "01-200-GRM-M" }
      },
      "product_pricing": {
        "advanced": false,
        "pricing_rules": [
          {
            "playbook": "Master_playbook_24",
            "price_format": "BASIC",
            "price_type": "SOLID",
            "price": "500",
            "default_discount": 0
          }
        ]
      }
    }
  ]
}

📘
Async Operation
This endpoint is asynchronous. On success, the API returns a request_id immediately:
{ "request_id": "4D114DAD97" }
Use this ID to track the result via the Get Asynchronous Request Status or Get Asynchronous Request Summary endpoints. The execution summary will log any per-SKU warnings or errors (for example, if a referenced SKU was not found in the catalog, or an attribute name does not exist in the version).

Next Steps

Handling Asynchronous Requests: Learn how to poll for status and interpret execution summaries.
Updating the Product Catalog: Learn how to use the POST endpoint to create products or fully replace their definitions.

📘
Related API Reference

Update Product Catalog Items