openapi: 3.2.0
info:
  title: Version Product Hierarchy (Beta) API
  description: 'This API provides a comprehensive set of services for managing versions and the associated product catalog within the DealHub CPQ system. It allows for system-to-system integration to get, create, duplicate, activate, and manage the content of versions.


    Several operations, such as duplicating, activating, and uploading a product catalog, are asynchronous. These endpoints return a `request_id` for tracking.


    All requests require a secret Bearer Token in the `Authorization` header, which is generated by a CPQ administrator.'
  version: 1.0.0
servers:
- url: https://api.dealhub.io
  description: The base URL for your DealHub instance.
  variables:
    your-dealhub-instance:
      default: app
      description: Your specific DealHub instance name (e.g., 'app', 'service-eu1').
security:
- bearerAuth: []
tags:
- name: Product Hierarchy (Beta)
paths:
  /api/beta/version/{version_id}/product-hierarchy:
    get:
      tags:
      - Product Hierarchy (Beta)
      summary: Get Product Hierarchy
      description: Retrieves the product hierarchy tree for a specific version.
      operationId: getProductHierarchy
      parameters:
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The identifier of the version.
      responses:
        '200':
          description: Success. Returns the product hierarchy.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductHierarchyNode'
              examples:
                getProductHierarchyExample:
                  summary: Example of a product hierarchy response
                  value:
                  - element:
                      type: PRODUCT
                      mandatory: false
                      nameOrSku: product 1
                      alternative: false
                    children":
                    - element:
                        type: PRODUCT
                        mandatory: false
                        nameOrSku: product 3
                        alternative: false
                      children: []
                  - element:
                      type: PRODUCT
                      mandatory: false
                      nameOrSku: product 4
                      alternative: false
                    children:
                    - element:
                        type: LABEL
                        mandatory: true
                        nameOrSku: Label A
                        alternative: false
                      children:
                      - element:
                          type: PRODUCT
                          mandatory: false
                          nameOrSku: product 5
                          alternative: false
                        children: []
                      - element:
                          type: PRODUCT
                          mandatory: true
                          nameOrSku: product 6
                          alternative: false
                        children": []
                    - element:
                        type: LABEL
                        mandatory: false
                        nameOrSku: Label B
                        alternative: false
                      children:
                      - element:
                          type: PRODUCT
                          mandatory: false
                          nameOrSku: product 1
                          alternative: false
                        children:
                        - element:
                            type: PRODUCT
                            mandatory: false
                            nameOrSku: product 4
                            alternative: false
                          children: []
    post:
      tags:
      - Product Hierarchy (Beta)
      summary: Create or Update Product Hierarchy
      description: Asynchronously creates or updates the product hierarchy for a 'DRAFT' version. This operation returns a `request_id` for tracking.
      operationId: updateProductHierarchy
      parameters:
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The identifier of the 'DRAFT' version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ProductHierarchyNode'
            examples:
              updateProductHierarchyExample:
                summary: Example of updating a product hierarchy
                value:
                - element:
                    type: PRODUCT
                    mandatory: false
                    nameOrSku: product 1
                    alternative: false
                  children:
                  - element:
                      type: PRODUCT
                      mandatory: false
                      nameOrSku: product 3
                      alternative: false
                    children: []
                - element:
                    type: PRODUCT
                    mandatory: false
                    nameOrSku: product 4
                    alternative: false
                  children:
                  - element:
                      type: LABEL
                      mandatory: true
                      nameOrSku: Label A
                      alternative: false
                    children:
                    - element:
                        type: PRODUCT
                        mandatory: false
                        nameOrSku: product 5
                        alternative: false
                      children: []
                    - element:
                        type: PRODUCT
                        mandatory: true
                        nameOrSku: product 6
                        alternative: false
                      children: []
                  - element:
                      type: LABEL
                      mandatory: false
                      nameOrSku: Label B
                      alternative: false
                    children:
                    - element:
                        type: PRODUCT
                        mandatory: false
                        nameOrSku: product 1
                        alternative: false
                      children:
                      - element:
                          type: PRODUCT
                          mandatory: false
                          nameOrSku: product 4
                          alternative: false
                        children: []
      responses:
        '200':
          description: Success. The update process has started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
    delete:
      tags:
      - Product Hierarchy (Beta)
      summary: Delete from Product Hierarchy
      description: Asynchronously deletes specified items (products, bundles, or labels) from the product hierarchy of a 'DRAFT' version.
      operationId: deleteFromProductHierarchy
      parameters:
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 16
        description: The identifier of the 'DRAFT' version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items_to_delete:
                  type: array
                  items:
                    type: object
                    properties:
                      nameOrSku:
                        type: string
      responses:
        '200':
          description: Success. The deletion process has started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
components:
  schemas:
    ProductHierarchyNode:
      type: object
      properties:
        nameOrSku:
          type: string
          description: The SKU of the product/bundle or the name of the label.
        type:
          type: string
          enum:
          - PRODUCT
          - BUNDLE
          - LABEL
          description: The type of the hierarchy item.
        mandatory:
          type: boolean
          description: Whether the item is mandatory.
        alternative:
          type: boolean
          description: Whether the item is an alternative choice.
        children:
          type: array
          items:
            $ref: '#/components/schemas/ProductHierarchyNode'
          description: A nested list of child items.
    AsyncResponse:
      type: object
      properties:
        request_id:
          type: string
          description: The ID of the asynchronous request for tracking.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A secret token generated by a CPQ administrator.