Guides

Version API Overview

Suggest Edits

The Version Open API provides a set of services for managing the configuration of your DealHub CPQ environment. In DealHub, a Version is the fundamental container that holds all your business logic, including product definitions, pricing rules, discount policies, and approval workflows.

This API is designed for system-to-system integration, allowing you to manage the lifecycle of your sales configuration. Common use cases include:

  • Synchronizing Products: Automatically pushing product catalog updates from an ERP or PLM system into DealHub.
  • Deployment Automation: Promoting configurations from a Sandbox environment to Production.
  • Configuration Auditing: Retrieving the exact product and pricing rules used for a specific period.

The Version Lifecycle

Understanding the status of a version is critical for using this API. A version in DealHub will always be in one of three states, and the state determines what operations you can perform.

1. Draft

A DRAFT version is your working copy. It is the only state where data is editable. You can upload new product catalogs, define hierarchies, and modify pricing rules only when a version is in Draft status.

  • You can have multiple Draft versions in the system.
  • This is where you prepare changes before they go live to your sales team.

2. Active

The ACTIVE version is the live configuration currently used by your sales representatives to generate quotes.

  • There can be only one Active version at a time.
  • Active versions are read-only to ensure traceability. You cannot change the configuration of a live version.
  • To update your live configuration, you must create a new Draft, make changes, and then activate it.

3. Deactivated

When you activate a new Draft version, the previously Active version automatically moves to DEACTIVATED status.

  • These versions serve as an archive for historical data.
  • They cannot be edited, but you can retrieve their data for auditing purposes.

Asynchronous Processing

Many operations in the Version API, such as uploading a large product catalog, duplicating a version, or activating a version, are potentially time-consuming. To prevent timeouts and ensure system stability, these operations are handled asynchronously.

To use the Version API, you will typically execute the following steps:

  1. Initiate the Request: When you send a request (e.g., to upload products), the API will immediately return an HTTP 200 success response containing a request_id.

    {
  "request_id": "4D114DAD97"
}

  2. Processing: DealHub processes the task in the background.

  3. Check Status: You can track the completion of the task in two ways:

    • Polling: Periodically call the Get Asynchronous Request Status endpoint using your request_id to see if the status is done, in-progress, or failed.
    • Webhooks: Subscribe to system events to receive a notification automatically when the process completes.

📘

Best Practice

DealHub recommends you to use Webhooks to listen for completion events rather than constantly polling the API. This is more efficient and reduces API traffic.

Authentication

Like other DealHub APIs, the Version API uses a secure token-based authentication system. Every request must include a DealHub Authentication Token in the header, following the structure:

`Authorization: Bearer <YOUR_SECRET_TOKEN>`

📘

Admin Access Required

This token must be generated by a CPQ Administrator within the DealHub system settings and shared securely with your integration team.

BETA Services: Product Hierarchy

The Version API is currently being expanded to include new BETA services for managing Product Hierarchy. These endpoints allow you to define complex relationships between products, bundles, and labels using a tree structure.

You can use these services to:

  • Define parent-child relationships between products.
  • Set mandatory or alternative selection rules.
  • Upload complete hierarchy trees to a Draft version.

📘

Beta Functionality

Please note that hierarchy management endpoints are currently in Beta. Ensure you test these features in a Sandbox environment before deploying to Production.

Next Steps

Now that you understand the core concepts of versions and asynchronous processing, you can proceed to the practical guides:

Updated 18 days ago