The endpoint contract a DealHub customer implements so DealHub can retrieve real-time product prices and attributes from an external system such as an ERP while a quote is being generated. The server URL in the published spec is a documented placeholder — the real endpoint URL is configured per tenant in DealHub Version Settings, so this entry has no DealHub-hosted base URL.
openapi: 3.0.3
info:
title: Callout API
description: 'This API defines the contract for an external system that DealHub calls out to for retrieving real-time prices
and product attributes. This is known as the "Callouts API".
When a sales representative adds a product configured for "ERP Pricing" to a quote, DealHub sends a POST request to the
endpoint defined here. The external system is expected to process the request and return the calculated values for each
line item.'
version: 1.0.1
servers:
- url: https://your-external-system.com/api/pricing
description: This is a placeholder URL. The actual, full endpoint URL that DealHub calls is configured by an administrator
in the DealHub Version Settings > Advanced Settings > Callouts UI.
security:
- bearerAuth: []
- basicAuth: []
paths:
/:
post:
tags:
- Callouts
summary: Retrieve Real-Time Pricing
description: '> ❗️ Important
>
> This is not an endpoint provided by DealHub. This page present the endpoint definition you need to make available
so DealHub can call it.
This endpoint enables DealHub to retrieve real-time product prices and attributes from your external system while
a quote is being generated.
The specific URL for this endpoint is configured by the administrator in the DealHub UI.
> 📘 Date Formats
>
> All date and time values are provided in ISO 8601 format and standardized to UTC (Coordinated Universal Time) `yyyy-MM-dd''T''HH:mm:ss.SSS''Z''`
(e.g., `2025-09-01T15:39:25Z`).'
operationId: getPricing
requestBody:
description: A request from DealHub containing quote context and a list of items requiring pricing.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CalloutRequest'
examples:
calloutRequestExample:
summary: Request example
value:
request_id: RANDOM-32bit-string
authentication: DASFE$df422ffg
playbook_answers:
general.currency: USD
general.geo: North America
group1.customer_type: Enterprise
group2.number_of_something: 4323.11
group3.proposal_date: '2021-03-25T15:39:25Z'
items:
- id: 1
sku: A-1
type: product
quantity: 15
duration: 12
family: hardware
returned_attributes:
price: number
MSRP: number
partner_discount1: percentage
partner_discount2: percentage
start_date: date
- id: 2
sku: B-1
type: bundle
quantity: 2
duration: 24
family: software
returned_attributes:
MSRP: number
start_date: date
bundle_items:
- id: 3
sku: B-111
type: product
quantity: 15
duration: 12
family: hardware
returned_attributes:
price: number
MSRP: number
partner_discount1: percentage
partner_discount2: percentage
start_date: date
- id: 4
sku: B-222
type: product
quantity: 15
duration: 12
family: hardware
returned_attributes:
price: number
MSRP: number
partner_discount1: percentage
partner_discount2: percentage
start_date: date
- id: 5
sku: B-333
type: product
quantity: 15
duration: 12
family: hardware
returned_attributes:
price: number
MSRP: number
partner_discount1: percentage
partner_discount2: percentage
start_date: date
responses:
'200':
description: Successful response containing the calculated prices and attributes for each item.
content:
application/json:
schema:
$ref: '#/components/schemas/CalloutResponse'
examples:
calloutResponseExample:
summary: Expected response example
value:
items:
- id: 1
sku: A-1
list_price: 100
MSRP: 200
partner_discount1: 10
partner_discount2: 10
start_date: '2021-03-25T15:39:25Z'
- id: 2
sku: B-1
MSRP: 600
start_date: ''
bundle_items:
- id: 3
sku: B-111
list_price: 100
MSRP: 200
partner_discount1: 10
partner_discount2: 10
start_date: '2021-03-25T15:39:25Z'
- id: 4
sku: B-222
list_price: 100
MSRP: 200
partner_discount1: 10
partner_discount2: 10
start_date: '2021-03-25T15:39:25Z'
- id: 5
sku: B-333
list_price: 100
MSRP: 200
partner_discount1: 10
partner_discount2: 10
start_date: '2021-03-25T15:39:25Z'
'400':
description: Bad Request. An error occurred in the external system. The response should contain a clear error message.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token authentication. The token is provided by the DealHub admin during Callout configuration.
basicAuth:
type: http
scheme: basic
description: Basic authentication with username and password. Credentials are provided by the DealHub admin during Callout
configuration.
schemas:
CalloutRequest:
type: object
properties:
request_id:
type: string
description: A unique, randomly generated string to identify the request.
authentication:
type: string
description: Authentication details passed in the request body. This value mirrors the content of the `Authorization`
header.
playbook_answers:
type: object
description: A key-value map of playbook answers selected by the administrator in the Callout configuration. The
keys and value types are customer-specific.
additionalProperties: true
items:
type: array
description: List of items (products or bundles) for pricing.
items:
$ref: '#/components/schemas/Item'
required:
- items
- request_id
Item:
type: object
description: Represents a single product or a bundle within the quote. Can contain additional, customer-defined product
attributes configured by the admin.
properties:
id:
type: integer
format: int64
description: A unique number that identifies the item within this request. Must be returned in the response.
sku:
type: string
description: The SKU of the product or bundle.
type:
type: string
enum:
- product
- bundle
description: The type of the item.
quantity:
type: number
duration:
type: number
returned_attributes:
type: object
description: A list of attributes and their expected data types that DealHub is configured to receive for this item.
This serves as a guide for the expected response structure.
additionalProperties:
type: string
enum:
- number
- percentage
- date
bundle_items:
type: array
description: A list of child items. This is mandatory if the `type` is `bundle`.
items:
$ref: '#/components/schemas/Item'
required:
- id
- sku
- type
additionalProperties: true
CalloutResponse:
type: object
required:
- items
properties:
items:
type: array
description: The list of items with their calculated prices and attributes.
items:
$ref: '#/components/schemas/ResponseItem'
BaseResponseItem:
type: object
description: Common properties for any item returned in the response.
required:
- id
- sku
properties:
id:
type: integer
format: int64
description: Same 'id' as sent in the request payload.
sku:
type: string
description: Same 'sku' as sent in the request payload.
MSRP:
type: number
format: float
description: Manufacturer's Suggested Retail Price.
partner_discount1:
type: number
format: float
description: Partner discount value (e.g., 10 for 10%).
partner_discount2:
type: number
format: float
description: Partner discount value (e.g., 10 for 10%).
start_date:
type: string
format: date-time
description: A date value, expected in ISO 8601 format (e.g., "2025-09-01T15:39:25Z").
additionalProperties: true
ProductResponseItem:
description: Represents a single product with a mandatory price.
allOf:
- $ref: '#/components/schemas/BaseResponseItem'
- type: object
required:
- list_price
properties:
list_price:
type: number
format: float
description: List price of the line item. This field is mandatory for every product item.
BundleResponseItem:
description: Represents a bundle containing other items. The top-level bundle may not have a price itself.
allOf:
- $ref: '#/components/schemas/BaseResponseItem'
- type: object
required:
- bundle_items
properties:
bundle_items:
type: array
description: A list of child items within the bundle. Each item in this list must have a price.
items:
$ref: '#/components/schemas/ProductResponseItem'
ResponseItem:
oneOf:
- $ref: '#/components/schemas/ProductResponseItem'
- $ref: '#/components/schemas/BundleResponseItem'
description: An item in the response can be either a single product or a bundle.
ErrorResponse:
type: object
properties:
message:
type: string
description: A formatted error message from the external system that will be displayed to the user in the DealHub
UI.
required:
- message
x-readme:
explorer-enabled: true
proxy-enabled: true