Guides

Manage Versions

Suggest Edits

This guide walks you through the standard workflow for managing your DealHub CPQ configuration lifecycle. In DealHub, you cannot edit the live (ACTIVE) version directly. Instead, you must follow a cycle of duplicating the active version, modifying the new draft, and then activating it.

Prerequisites

  • DealHub Authentication Token: You must have a valid Bearer token.
  • Admin Access: Ensure your token has the necessary permissions to manage versions.

The Version Workflow

To update your product catalog or business logic safely, follow this sequence:

  1. Check Status: Identify the current ACTIVE version and ensure no conflicting DRAFT versions exist.
  2. Duplicate: Create a new DRAFT by duplicating the ACTIVE version.
  3. Modify: Use the Product Catalog APIs to make your changes (covered in Updating the Product Catalog).
  4. Activate: Promote your DRAFT to ACTIVE, which automatically deactivates the previous version.

Step 1: Check Current Version Status

Before starting any updates, you should identify the current active version ID. It is also a best practice to check if any DRAFT versions already exist.

🚧

Best Practice

If a DRAFT version already exists, we recommend stopping the automated process and alerting an administrator. This prevents your automation from overwriting work that a human admin might be doing manually .

Use the GET /versions endpoint (Get a List of Versions) with status filters to retrieve the relevant IDs.

curl --location 'https://api.dealhub.io/api/v1/versions?status=ACTIVE&status=DRAFT' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

The response will return a list of version objects. You need to parse this list to find the version_id where status is ACTIVE.

[
    {
        "name": "Q3 Pricing Update",
        "status": "ACTIVE",
        "version_id": "765379899",
        "comment": "Released in July"
    }
]

Step 2: Create a New Draft (Duplication)

Once you have the ACTIVE version ID, you can create a new working copy. This is done using the Duplicate Version endpoint. Send a POST request to /api/v2/version/duplicate. You must provide the version_id of the source version (the Active one you found in Step 1) and a name for the new version .

{
  "version_id": "765379899",
  "new_version_name": "Q4 Automation Update",
  "comment": "Automated creation via API"
}

📘

Promoting from Sandbox to Production

If you are deploying changes from a Sandbox environment to Production, you can include the to_account_instance parameter. This duplicates the version directly into the target account. Note that this request must be initiated from the Sandbox account .

Duplicating a version is an asynchronous operation. The API will immediately return a 200 OK status with a request_id. You must wait for this process to complete before you can edit the new draft .

{
  "request_id": "4D114DAD97"
}

Refer to the Handling Asynchronous Requests guide to learn how to poll for the status of this operation.

Step 3: Activate the Version

After you have successfully duplicated the version and finished uploading your product changes (see Updating the Product Catalog), the final step is to make the version live.

Send a POST request to /api/v1/version/activate (Activate a Version) using the version_id of your new draft .

{
  "version_id": "888444999"
}

After you activate the version, the following steps are going to happen:

  1. Asynchronous Processing: Like duplication, this returns a request_id. You must monitor the status to ensure activation succeeds .

  2. Status Change: Once successful, your Draft version status changes to ACTIVE.

  3. Deactivation: The version that was previously active automatically moves to DEACTIVATED status .

Next Steps

Now that you know how to manage the version container, learn how to modify the data inside it:

Updated 18 days ago