DealHub Callouts API

openapi: 3.2.0
info:
  title: Callouts 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: []
tags:
- name: Callouts
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:
  schemas:
    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
    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
    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'
    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'
    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.
    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
    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.
    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
  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.
x-readme:
  explorer-enabled: true
  proxy-enabled: true