Simulate a Quote via API

This tutorial teaches you how to use the Simulate Quote API. This is a headless operation that allows your backend systems or custom applications to get real-time pricing and product configuration data from DealHub without creating an actual quote object in the system.

The primary use cases for this feature include powering self-service customer portals, calculating prices for automated contract renewals, or validating complex configurations before a final quote is generated. The key difference between this and other APIs is that Simulate Quote returns a JSON calculation, whereas the Generate Quote API creates an official quote record in DealHub.

Prerequisites

Before you use the Simulate Quote API, an administrator must complete the necessary setup in a DRAFT version within DealHub. Ensure you have the following:

• DealHub Admin Access.
• API Playbook Enabled and Configured.
• A valid DealHub Authentication Token for making API calls.

Step 1: Construct the API Request Payload

To define what will be quoted, you must construct a JSON payload. The Simulate Quote API provides two primary methods for this: injecting data into the playbook using quote_data, or pushing product line items directly using line_items.

Option A: Inject Data via Playbook (quote_data)

This is the most common method because it leverages the full power of the DealHub CPQ engine. By sending answers to playbook questions, you allow DealHub to handle complex logic. This includes product selection rules, dynamic pricing, and validations, so you don't have to replicate them in your own application.

You simulate a user's choices, and DealHub returns the calculated result based on the logic configured in the API Playbook, The structure requires you to specify the group_id of the question group and a questions array containing each question_id and its value.

Use this method when you want to leverage the product selection rules, pricing logic, and validations built into the API Playbook, the following code snippet shows an example of how to use quote_data to send data.

{
  "version_id": "754c01-YOUR-VERSION-ID",
  "geo_code": "US",
  "currency": "USD",
  "quote_data": [
    {
      "group_id": "GQ",
      "questions": [
        {
          "question_id": "product",
          "value": "Admin License"
        },
        {
          "question_id": "qty",
          "value": 5
        }
      ]
    }
  ]
}

Option B: Inject Products Directly (line_items)

This method bypasses the Playbook's question-based logic and allows you to specify products directly by their sku. You can also inject attributes like list_price, net_price, and discount.

Use this method when your external system already knows exactly which products and prices to quote, and you don't need to rely on the Playbook's selection rules, the following code snippet shows an example of how to use line_items to send data.

{
  "version_id": "754c01-YOUR-VERSION-ID",
  "geo_code": "US",
  "currency": "USD",
  "line_items": [
    {
      "sku": "ADMIN-LIC",
      "qty": 5,
      "list_price": 100,
      "term_duration": 24
    }
  ]
}

Payload Parameters

The following table details all possible top-level fields for the request body.

📘

*Required Parameters

You must provide one of the following two options to simulate a quote, these options are mutually exclusive and cannot be used in the same request:

• external_opportunity_id: Use this when your quote relies on running CRM or API queries.
• geo_code and currency: Use this for simpler simulations that do not require external data queries.

🚧

Restrictions

• You cannot push quote_data into a question group that is also configured to use an External Query. This will cause a conflict.
• You cannot push data directly into a playbook field that is set as a Calculated Answer.

Step 2: Send the Request and Handle the Response

Send a POST request to your DealHub environment's Simulate Quote endpoint. A successful simulation will return a 200 OK status with a JSON payload containing the full calculation results. The following code snipet shows an response example:

{
    "currency": "USD",
    "total_list_price": 12000,
    "total_net_price": 12000,
    "total_discount": 0,
    "line_items": [
        {
            "id": "c7a8-internal-id-b729",
            "sku": "ADMIN-LIC",
            "qty": 5,
            "list_price": 100,
            "net_price": 100,
            "term_duration": 24,
            "attributes": {}
        }
    ],
    "proposal_attributes": {},
    "approval_flows": []
}

This response data can then be used to dynamically display pricing in your custom application or to validate a configuration before proceeding to the Generate Quote step.

Next Steps

Learn how to create a quote using the API by sending a JSON payload with all the required configuration data.