openapi: 3.0.3 info: title: Version 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: Version Management description: Endpoints for retrieving, creating, and managing versions. - name: Playbook description: Endpoints for exporting Playbook configuration and data in JSON format, and for generating a Generate Quote API request template based on the Playbook structure. - name: Product Catalog description: Endpoints for managing the product catalog within a specific version. - name: Asynchronous Operations description: Endpoints for tracking the status of asynchronous requests. - name: Beta description: New endpoints that are currently in beta. paths: /api/v1/version/id/{version_id}: get: tags: - Version Management summary: Get Version by ID description: Retrieve a specific Version based on its unique DealHub ID. operationId: getVersionById parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The unique identifier of the version. responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Version' examples: getVersionExample: summary: Successful response value: name: Master v1 comment: '' status: ACTIVE version_id: '67657' /api/v1/version/name/{version_name}: get: tags: - Version Management summary: Get Version by Name description: Retrieve a specific Version based on its name. operationId: getVersionByName parameters: - name: version_name in: path required: true schema: type: string maxLength: 120 description: The name of the version. responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Version' examples: getVersionExample: summary: Successful response value: name: Master v1 comment: '' status: ACTIVE version_id: '67657' /api/v1/versions: get: tags: - Version Management summary: Get a List of Versions description: Retrieve a list of Versions, with an option to filter by status. If no parameters are provided, it returns all versions. operationId: getVersions parameters: - name: status in: query schema: type: string enum: - DRAFT - ACTIVE - DEACTIVATED description: Search for Version(s) based on status. responses: '200': description: Success. Returns a list of version objects. content: application/json: schema: type: array items: $ref: '#/components/schemas/Version' examples: getVersionsExample: summary: Example list of versions value: - name: v3a comment: '' status: DEACTIVATED version_id: 068DoObdli5GuF14 - name: msd6 comment: '' status: DEACTIVATED version_id: 0AjX3aABgLN9f8uG /api/v1/version/duplicate: post: tags: - Version Management summary: Duplicate a Version description: Asynchronously creates a new Version entity based on an existing one. This operation returns a `request_id` for tracking. operationId: duplicateVersion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DuplicateVersionRequest' examples: duplicateVersionExample: summary: Duplicate a version to a new instance value: version_id: '765379899' new_version_name: New Version comment: Adding more BroadBand services to_account_instance: Account abc responses: '200': description: Success. The duplication process has started. content: application/json: schema: $ref: '#/components/schemas/AsyncResponse' examples: asyncResponseExample: summary: Successful response value: request_id: 4D114DAD97 /api/v1/version/activate: post: tags: - Version Management summary: Activate a Version description: Asynchronously activates a `DRAFT` Version. This operation returns a `request_id` for tracking. operationId: activateVersion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActivateVersionRequest' examples: activateVersionExample: summary: Request to activate a version value: version_id: '765379899' responses: '200': description: Success. The activation process has started. content: application/json: schema: $ref: '#/components/schemas/AsyncResponse' examples: asyncResponseExample: summary: Successful response value: request_id: 4D114DAD97 /api/version/{versionName}/playbook/{playbookId}/export: get: tags: - Playbook summary: Get Playbook Data description: 'Retrieves the details of the requested Playbook in a specific version, exporting the Playbook configuration and data in JSON format. Date-type attributes and playbook questions are returned in the format `yyyy-mm-dd hh:mm:ss`. The result might differ, depending on the requested features.' operationId: exportPlaybookData parameters: - name: versionName in: path required: true schema: type: string description: Version name. - name: playbookId in: path required: true schema: type: string description: Playbook name (not the Playbook display name). responses: '200': description: Success. Returns the Playbook details if a valid identifier is provided. content: application/json: schema: $ref: '#/components/schemas/PlaybookExportResponse' examples: exportPlaybookDataExample: summary: Successful response value: playbook_metadata: name: API display: API document_type: - PDF geo_factors_settings: true present_proposal_summary: true enable_partner_support: false sync_document_settings: enabled: RULE_BASED based_on: '[QG1.name] = [QG2.question_1]' sync_product_settings: enabled: NEVER based_on: null playbook_data: - group_id: QG1 group_name: QG1 group_type: QUESTIONS_GROUP group_external_object: '' question_data: - question_id: name question: name question_type: Text list answers: 1;2 default_answer: '1' - question_id: address question: address question_type: Text list answers: 1;2;3 default_answer: '1' - group_id: QG2 group_name: QG2 group_type: REPEATABLE_GROUP group_external_object: '' question_data: - question_id: question_1 question: question 1 question_type: Text list answers: answer default_answer: answer - question_id: question_2 question: question 2 question_type: Text list answers: answer 2 default_answer: answer 2 /api/version/{versionId}/playbook/{playbookId}/generate-quote-template: get: tags: - Playbook summary: Get Generate Quote Template description: 'Returns a preformatted JSON template for API quote generation based on the Playbook structure. Use this template as the starting point for Generate Quote API requests. Date-type attributes and playbook questions are returned in the format `yyyy-mm-dd hh:mm:ss`. Template generation rules: - The template includes all required API fields. - The template includes default values if they exist. Otherwise, it uses the first available answer. - The template excludes calculated questions.' operationId: getGenerateQuoteTemplate parameters: - name: versionId in: path required: true schema: type: string description: Version name. - name: playbookId in: path required: true schema: type: string description: Playbook name (not the Playbook display name). responses: '200': description: Success. Returns the Generate Quote template JSON. content: application/json: schema: $ref: '#/components/schemas/GenerateQuoteTemplateResponse' examples: generateQuoteTemplateExample: summary: Template JSON structure value: external_opportunity_id: '' request_action: draft line_item_details: basic playbook: quote_name: '' dealroom_publish_name: '' total_sales_discount: 0 expiration_date: '' document_type: PDF timezone_offset: 0 partner_program: - partner_level_name: '' program_name: '' quote_data: - group_id: questions: - : '' : '' line_items: - sku: item_name: '' bundle_ref_sku: '' bundle_ref_id: 0 list_price: 0 net_price_per_unit: 0 net_price: 0 msrp: 0 msrp_discount: 0 sales_discount: 0 total_discount: 0 product_factors: Quantity: 1 Duration: 1 attributes: : '' : 0 : YYYY-MM-DD partner_program_data: - partner_program_name: '' partner_level_item_price: 0 partner_level_item_discount: 0 sign_externally_comment: '' '400': description: Bad Request. Invalid versionId. content: application/json: schema: $ref: '#/components/schemas/PlaybookErrorResponse' '404': description: Playbook not found. content: application/json: schema: $ref: '#/components/schemas/PlaybookErrorResponse' examples: playbookNotFoundExample: summary: Error response value: error: Playbook not found code: 404 '500': description: Failed to generate JSON. content: application/json: schema: $ref: '#/components/schemas/PlaybookErrorResponse' /api/v1/version/{version_id}/products: get: tags: - Product Catalog summary: Get Products of a Version description: 'Retrieves a paginated list of products for a specific version, returning basic product attributes and price details. - `DRAFT` Status: Returns the full product list. - `ACTIVE`/`DEACTIVATED` Status: Can return either all products or only products that were new or modified compared to the previously active version.' operationId: getVersionProducts parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The unique identifier of the Version. - name: offset in: query schema: type: integer minimum: 0 maximum: 10000 description: The number of products to skip for pagination. - name: limit in: query schema: type: integer minimum: 1 maximum: 1000 description: The maximum number of products to return. If the requested `limit` value exceeds the maximum allowed limit, the system will automatically cap the result set at the maximum limit. - name: product_option in: query schema: type: string enum: - ALL - MODIFIED default: ALL description: Specify whether to fetch all products or only new/updated products. - name: pricing_option in: query schema: type: string enum: - MIN - MAX - FIRST default: MIN description: For products with multiple fixed prices, specifies which price to return (Minimum, Maximum, or First defined). responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/VersionProductsResponse' examples: getVersionProductsExample: summary: Successful response value: info: version_id: '76472' version_status: ACTIVE compared_with_version_id: '76326' more_results_matching_the_request: true offset: '1' limit: '25' products: - sku: '56545' name: Product A type: PRODUCT description: Description of product A price: EUR: '10' USD: '12.5' attributes: - attr_x: value X - attr_y: value Y - sku: '56546' name: Product B type: PRODUCT description: Description of product B price: EUR: '18' USD: '21.5' attributes: - attr_x: value XX - attr_y: value YY - sku: 56545_b name: Bundle X type: BUNDLE description: Description of bundle X price: EUR: '10' attributes: - attr_x: value XYZ - attr_y: value YZ bundle_items: - '56545' - '56546' /api/v1/version/product_by_sku: post: tags: - Product Catalog summary: Get Products by SKU description: 'Retrieves basic details for a specific list of products from the catalog based on their SKUs. > 📘 > If some SKUs could not be found in a specific Version the system will return status 200, with error in the `info` structure.' operationId: getProductsBySku requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductsBySkuRequest' examples: getProductsBySkuExample: summary: Request specific products by SKU value: version_id: 23687268JS5 pricing_option: MAX sku: - Sku-123-dvvv - Sku-123-dvv2 - Sku-123-dvv3 responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/VersionProductsResponse' examples: getVersionProductsExample: summary: Successful response value: info: version_id: '76472' version_status: ACTIVE compared_with_version_id: '76326' more_results_matching_the_request: true offset: '1' limit: '25' products: - sku: '56545' name: Product A type: PRODUCT description: Description of product A price: EUR: '10' USD: '12.5' attributes: - attr_x: value X - attr_y: value Y - sku: '56546' name: Product B type: PRODUCT description: Description of product B price: EUR: '18' USD: '21.5' attributes: - attr_x: value XX - attr_y: value YY - sku: 56545_b name: Bundle X type: BUNDLE description: Description of bundle X price: EUR: '10' attributes: - attr_x: value XYZ - attr_y: value YZ bundle_items: - '56545' - '56546' /api/v1/version/products_excel/{version_id}: get: tags: - Product Catalog summary: Extract Products to Excel description: Retrieves all product-related information for a specific version in an Excel file format. operationId: extractProductsExcel parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The unique identifier of the Version. responses: '200': description: Success. Returns the Excel file as a byte array. content: application/vnd.ms-excel: schema: type: string format: binary /api/v1/version/{version_id}/products_catalog: get: tags: - Product Catalog summary: Get Product Catalog description: Retrieves paginated information about products and bundles in the catalog, including attributes, assignments, and pricing details. operationId: getProductCatalog parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The unique identifier of the Version. - name: sku in: query style: form explode: true schema: type: array items: type: string maxItems: 100 description: 'One or more product SKUs to filter the result. Can be used multiple times (e.g., `?sku=SKU001&sku=SKU002`). If none of the provided SKUs match, the service will return an empty list. In case you inform a list of SKUs, ‘limit’ and ‘offset’ parameters on request will be ignored if provided.' - name: offset in: query schema: type: integer default: 0 description: The number of products to skip for pagination. - name: limit in: query schema: type: integer default: 100 description: The maximum number of products to return. responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/ProductCatalogGetResponse' examples: getProductCatalogExample: summary: Successful response value: products: - sku: ABC-12345-S-BL name: GRM Service description: 'GRM Service ' tags: [] primary_tag: null merge_products: false product_attributes: Department: type: NUMBER value: '1022' Model: type: TEXT value: 01-200-GRM-M Manufacture Date: type: DATE value: May 31, 2024 product_assignments: - assignment: RULE_BASED playbook: Master_playbook_24 assignment_rules: - ordinal: 0 name: Seasonal assignment rule: '[General.partner_program] = "Direct Sales"' note: null product_factors: - name: Duration value: '12' applicable: true - name: Quantity value: '1' applicable: true - name: Sits value: '1' applicable: false proposal_attributes: - name: custom_proposal_attribute value: Direct applicable: true product_pricing: advanced: true pricing_rules: - playbook: Master_playbook_24 ordinal: 0 currency: null rule: '' price: '0' level: 0 note: null price_format: BASIC rounding_policy: null dynamic_price: false name: null price_type: SOLID apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: '100' default_discount: '0' based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} - playbook: Master_playbook_24 ordinal: 1 currency: null rule: 'true' price: '888' level: 0 note: null price_format: ADVANCED rounding_policy: null dynamic_price: false name: null price_type: SOLID apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: '100' default_discount: '0' based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} product_conditional_names: [] bundles: - sku: Products summary name: Products summary description: Products summary tags: - Products summary primary_tag: Products summary product_attributes: Department: type: NUMBER value: '1111' Model: type: TEXT value: '1117' Manufacture Date: type: DATE value: '1111' product_assignments: - assignment: RULE_BASED playbook: Master_playbook_24 assignment_rules: - ordinal: 0 name: bundle3 rule: '[FixedSummary_bundles.Add_products_summary_bundle] = "Yes"' note: null product_factors: - name: Duration value: '1' applicable: false - name: Quantity value: '1' applicable: true - name: Sits value: '1' applicable: false proposal_attributes: - name: custom_proposal_attribute value: '' applicable: true product_pricing: advanced: false pricing_rules: - playbook: Master_playbook_24 ordinal: 0 currency: null rule: '' price: '50' level: 0 note: null price_format: BASIC rounding_policy: null dynamic_price: false name: null price_type: FROM_ALL_QUOTE apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: '100' default_discount: '0' based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} product_conditional_names: [] bundle_type: PRODUCT_SUMMARY price_in_bundle_is_zero: false sync_to_crm: true sync_bundle_price: false bundle_items: - sku: Product2 ordinal: 1 how_to_add: AUTOMATIC enable_modify_factors: false product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '2' applicable: true - name: Sits value: '1' applicable: true - sku: Product3 ordinal: 2 how_to_add: MANUAL enable_modify_factors: true product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '3' applicable: true - name: Sits value: '0' applicable: true - sku: Product1 ordinal: 0 how_to_add: AUTOMATIC enable_modify_factors: true product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '1' applicable: true - name: Sits value: '0' applicable: true - sku: Product4 ordinal: 3 how_to_add: COMBINED enable_modify_factors: false product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '4' applicable: true - name: Sits value: '1' applicable: true info: version_id: 7b34133847401b12 version_status: DRAFT more_results_matching_the_request: false limit: 100 offset: 0 patch: tags: - Product Catalog summary: Update Product Catalog Items description: 'Asynchronously updates specific data elements for existing SKUs in a `DRAFT` version''s product catalog. Unlike the POST endpoint, this endpoint **does not** create new products — it only modifies data elements for SKUs that already exist in the catalog. This endpoint operates in one of two modes, defined by the `mode` query parameter: **UPDATE mode**: Only the data elements explicitly included in the request body are added or updated. Any existing data not referenced in the request remains unchanged. **REPLACE mode**: Each data category included in the request (e.g., `product_attributes`, `pricing_rules`) completely replaces the corresponding data for that SKU. Entries within an included category that are not present in the request are removed. Categories not referenced at all in the request are left untouched. This operation returns a `request_id` for you to track the progress. Requests targeting an `ACTIVE` or `DEACTIVATED` version will fail.' operationId: updateProductCatalogItems parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The identifier of the `DRAFT` version whose catalog should be updated. - name: mode in: query required: true schema: type: string enum: - UPDATE - REPLACE description: The update mode. `UPDATE` merges the provided data with existing data for each SKU; unspecified data is preserved. `REPLACE` replaces all entries within each included data category; entries not present in the request are removed from that category. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductCatalogPatchRequest' examples: patchProductCatalogExample: summary: Request example value: products: - sku: ABC-12345-S-BL product_attributes: Department: value: '1022' Model: value: 01-200-GRM-M Manufacture Date: value: May 31, 2024 product_pricing: advanced: true pricing_rules: - playbook: Master_playbook_24 currency: null rule: '' price: '0' level: 0 note: null price_format: BASIC rounding_policy: null dynamic_price: false name: Rule name price_type: SOLID apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: 100 default_discount: 0 based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} - playbook: Master_playbook_24 currency: null rule: 'true' price: '888' level: 0 note: null price_format: ADVANCED rounding_policy: null dynamic_price: false name: null price_type: SOLID apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: 100 default_discount: 0 based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} bundles: - sku: Products summary product_attributes: Department: value: '' Model: value: '' Manufacture Date: value: '' product_assignments: - assignment: RULE_BASED playbook: Master_playbook_24 assignment_rules: - ordinal: 0 name: bundle3 rule: '[FixedSummary_bundles.Add_products] = "Yes"' note: null product_factors: - name: Duration value: '1' applicable: false - name: Quantity value: '1' applicable: true - name: Sits value: '1' applicable: false proposal_attributes: - name: custom_proposal_attribute value: '' applicable: true product_pricing: advanced: false pricing_rules: - playbook: Master_playbook_24 currency: null rule: '' price: '50' level: 0 price_format: BASIC rounding_policy: null dynamic_price: false name: null price_type: FROM_ALL_QUOTE apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: 100 default_discount: 0 based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} bundle_items: - sku: Product1 ordinal: 0 how_to_add: AUTOMATIC enable_modify_factors: true product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '1' applicable: true - name: Sits value: '0' applicable: true - sku: Product2 ordinal: 1 how_to_add: AUTOMATIC enable_modify_factors: false product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '2' applicable: true - name: Sits value: '1' applicable: true responses: '200': description: The request was accepted and will be processed asynchronously. content: application/json: schema: $ref: '#/components/schemas/AsyncResponse' examples: patchProductCatalogResponseExample: summary: Successful response value: request_id: 4D114DAD97 '400': description: Bad Request. The request payload is invalid, a mandatory field is missing, or the specified version is not in `DRAFT` status. '403': description: Unauthenticated. The `Authorization` token is missing or invalid. post: tags: - Product Catalog summary: Create or Update Product Catalog description: 'This endpoint asynchronously uploads a complete product catalog to a `DRAFT` version. Each product and bundle is created or updated based on the details in the request JSON. If a SKU already exists in the catalog, it will be completely replaced with the new data from the request, including its pricing, assignments, and other details. If the replacement process fails for any reason, the system will revert to the old product definition. This operation returns a `request_id` for you to track the progress. Note that requests targeting an `ACTIVE` or `DEACTIVATED` catalog version will fail.' operationId: uploadProductCatalog parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The identifier of the 'DRAFT' version to upload the catalog to. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductCatalogPostRequest' examples: productCatalogExample: summary: Request example value: products: - sku: ABC-12345-S-BL name: GRM Service description: 'GRM Service ' tags: [] primary_tag: null merge_products: false product_attributes: Department: value: '1022' Model: value: 01-200-GRM-M Manufacture Date: value: May 31, 2024 product_assignments: - assignment: RULE_BASED playbook: Master_playbook_24 assignment_rules: - ordinal: 0 name: Seasonal assignment rule: '[General.partner_program] = "Direct Sales"' note: null product_factors: - name: Duration value: '12' applicable: true - name: Quantity value: '1' applicable: true - name: Sits value: '1' applicable: false proposal_attributes: - name: custom_proposal_attribute value: Direct applicable: true product_pricing: advanced: true pricing_rules: - playbook: Master_playbook_24 ordinal: 0 currency: null rule: '' price: '0' level: 0 note: null price_format: BASIC rounding_policy: null dynamic_price: false name: null price_type: SOLID apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: '100' default_discount: '0' based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} - playbook: Master_playbook_24 ordinal: 1 currency: null rule: 'true' price: '888' level: 0 note: null price_format: ADVANCED rounding_policy: null dynamic_price: false name: null price_type: SOLID apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: '100' default_discount: '0' based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} product_conditional_names: [] bundles: - sku: Products summary name: Products summary description: Products summary tags: - Products summary primary_tag: Products summary product_attributes: Department: value: '' Model: value: '' Manufacture Date: value: '' product_assignments: - assignment: RULE_BASED playbook: Master_playbook_24 assignment_rules: - ordinal: 0 name: bundle3 rule: '[FixedSummary_bundles.Add_products_summary_bundle] = "Yes"' note: null product_factors: - name: Duration value: '1' applicable: false - name: Quantity value: '1' applicable: true - name: Sits value: '1' applicable: false proposal_attributes: - name: custom_proposal_attribute value: '' applicable: true product_pricing: advanced: false pricing_rules: - playbook: Master_playbook_24 ordinal: 0 currency: null rule: '' price: '50' level: 0 note: null price_format: BASIC rounding_policy: null dynamic_price: false name: null price_type: FROM_ALL_QUOTE apply_to: GENERATED_ITEMS apply_to_templates: '' apply_to_rules: '' max_discount: '100' default_discount: '0' based_of_tags: '' based_of_price: null limit_type: AS_IS limit_min_value: null limit_max_value: null disable_rounding: false include_positive: false volume_discount: {} product_conditional_names: [] bundle_type: PRODUCT_SUMMARY price_in_bundle_is_zero: false sync_to_crm: true sync_bundle_price: false bundle_items: - sku: Product2 ordinal: 1 how_to_add: AUTOMATIC enable_modify_factors: false product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '2' applicable: true - name: Sits value: '1' applicable: true - sku: Product3 ordinal: 2 how_to_add: MANUAL enable_modify_factors: true product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '3' applicable: true - name: Sits value: '0' applicable: true - sku: Product1 ordinal: 0 how_to_add: AUTOMATIC enable_modify_factors: true product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '1' applicable: true - name: Sits value: '0' applicable: true - sku: Product4 ordinal: 3 how_to_add: COMBINED enable_modify_factors: false product_factors: - name: Duration value: '1' applicable: true - name: Quantity value: '4' applicable: true - name: Sits value: '1' applicable: true responses: '200': description: Success. The upload process has started. content: application/json: schema: $ref: '#/components/schemas/AsyncResponse' examples: uploadProductCatalogExample: summary: Successful response value: request_id: 4D114DAD97 /api/v1/version/{version_id}/products_catalog/all: delete: tags: - Product Catalog summary: Delete All Products from Catalog description: 'Deletes all products and the entire product hierarchy tree from a `DRAFT` version. * This operation can only be triggered for a catalog version with a **`DRAFT`** status. * Requests made for an `ACTIVE` or `DEACTIVATED` catalog version will fail with a `400 Bad Request` HTTP error.' operationId: deleteAllProducts parameters: - name: version_id in: path required: true schema: type: string maxLength: 16 description: The identifier of the 'DRAFT' version. responses: '200': description: Success. All products were deleted. '400': description: Bad Request. The operation cannot be performed on a catalog Version with a status of `ACTIVE` or `DEACTIVATED`. /api/v1/version/{version_id}/products_catalog/by_sku: delete: tags: - Product Catalog summary: Delete Specific Products by SKU description: "Deletes specific products from the product catalog of a `DRAFT` version. \n* This operation can only be\ \ triggered for a catalog version with a **`DRAFT`** status.\n* Requests made for an `ACTIVE` or `DEACTIVATED` catalog\ \ version will fail with a `400 Bad Request` HTTP error.\n\nA product cannot be deleted if it is:\n* A parent to another\ \ product in the hierarchy.\n* Marked as mandatory.\n* Set as an alternative in the hierarchy tree." operationId: deleteProductsBySku 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: skus: type: array items: type: string examples: deleteBySkuExample: summary: Delete two specific SKUs value: skus: - SKU-1 - SKU-45 responses: '200': description: Success. Specified products were deleted. '400': description: Bad Request. /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' /api/v1/request/{request_id}/status: get: tags: - Asynchronous Operations summary: Get Asynchronous Request Status description: Polls and retrieves the current status of a specific asynchronous request (e.g., duplicate version, activate version). operationId: getAsyncRequestStatus parameters: - name: request_id in: path required: true schema: type: string maxLength: 16 description: The ID of the asynchronous request. responses: '200': description: Success. Returns the current status of the request. content: application/json: schema: $ref: '#/components/schemas/RequestStatus' examples: requestStatusExample: summary: Example of a completed request status value: request_id: 4D114DAD97 status: done error_description: '' error_code: null /api/v1/request/{request_id}/summary: get: tags: - Asynchronous Operations summary: Get Asynchronous Request Execution Summary description: Retrieves a summary of a completed asynchronous process, including success, error, and warning counts. This is particularly useful for operations like product catalog uploads. operationId: getAsyncRequestSummary parameters: - name: request_id in: path required: true schema: type: string maxLength: 16 description: The ID of the asynchronous request. responses: '200': description: Success. Returns the execution summary. content: application/json: schema: $ref: '#/components/schemas/RequestSummaryResponse' examples: requestSummaryExample: summary: Example of a request summary with warnings value: status: Completed summary: success_count: 1 errors_count: 0 warnings: - 'Missing currency in price item for SKU KY014X, using default currency: USD' errors: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: A secret token generated by a CPQ administrator. schemas: Version: type: object properties: name: type: string description: Name of the version. comment: type: string description: Comment provided during version creation. status: type: string description: Status of the version. version_id: type: string description: The unique identifier of the version. DuplicateVersionRequest: type: object required: - version_id - new_version_name properties: version_id: type: string maxLength: 16 description: ID of the version that should be duplicated. new_version_name: type: string maxLength: 120 description: Name for the new version. comment: type: string maxLength: 4000 description: Comments for the newly created version. to_account_instance: type: string description: Instance name of the Account where the version should be duplicated to (e.g., for Sandbox to Production). ActivateVersionRequest: type: object required: - version_id properties: version_id: type: string maxLength: 16 description: ID of the Version that should be activated. AsyncResponse: type: object properties: request_id: type: string description: The ID of the asynchronous request for tracking. Info: type: object properties: version_id: type: string description: The ID of the version for which products were retrieved. version_status: type: string description: The status of the version. compared_with_version_id: type: string description: The ID of the version that was replaced by this one upon activation. more_results_matching_the_request: type: boolean description: Flag indicating if more results are available for pagination. offset: type: string description: The offset used in the request. limit: type: string description: The limit used in the request. error: type: string description: Error message if not all requested data could be retrieved. ProductBasic: type: object properties: sku: type: string description: Product catalog unique identifier. name: type: string description: Product name. type: type: string enum: - PRODUCT - BUNDLE description: Type of the product. description: type: string description: Product description. price: type: object description: List of price & currency pairs. additionalProperties: type: string attributes: type: array description: List of all product attributes defined for the version. items: type: object additionalProperties: type: string bundle_items: type: array description: List of Product SKUs in the bundle (if type is BUNDLE). items: type: string VersionProductsResponse: type: object properties: info: $ref: '#/components/schemas/Info' products: type: array items: $ref: '#/components/schemas/ProductBasic' ProductsBySkuRequest: type: object required: - sku properties: version_id: type: string maxLength: 16 description: ID of the version. If omitted, the active version is used. pricing_option: type: string enum: - MIN - MAX - FIRST description: Specifies which price to return for SKUs with multiple fixed prices. sku: type: array items: type: string maxLength: 200 description: List of SKUs to retrieve. ProductAttribute: type: object properties: type: type: string enum: - DATE - TEXT - TEXT_LIST - NUMBER - BOOLEAN - COGS value: type: string ProductFactor: type: object required: - name properties: name: type: string description: The name of the factor. Must match an existing factor name configured in the CPQ version. value: type: string default: '1' description: The factor value. This field may have a value even when the factor is not applicable. applicable: type: boolean default: false description: Indicates if the factor is applicable in the context of the assignment rule. ProposalAttribute: type: object required: - name - value properties: name: type: string maxLength: 50 description: The name of the proposal attribute. value: type: string maxLength: 2000 description: Attribute value. If `null` is provided, the system will define this attribute as not applicable in the context of the assignment rule. applicable: type: boolean default: false description: Indicates if the attribute is applicable in the context of the assignment rule. VolumeDiscount: type: object description: 'Defines the volume discount tables associated with the pricing rule. The value must be a key-value map where each entry represents a pair in the format <factor_name>: <volume_discount_table_name>. The factor_name corresponds to the pricing factor (e.g., Quantity, Duration), and the value specifies the volume discount table applied to that factor.

Example:
"volume_discount": { "Quantity": "VolD1", "Duration": "VolD2" }' example: Quantity: VolD1 Duration: VolD2 additionalProperties: type: string PricingRuleProduct: description: 'List of the product pricing rules. The order of the elements in this list determines the sequence in which the pricing rules are evaluated by the CPQ system.
If advanced: false`, the pricing_rules list should have only **1 rule definition** with price_format: BASIC`.
If such configuration won’t be provided in the request, the system will create a default rule with price 0.
In case there are more than 1 rule in the pricing_rules list with price_format: BASIC`, the system will use the 1st definition and the rest will be ignored.
If advanced: true`, the pricing_rules list must have at least **1 rule definition** with price_format: ADVANCED`. Otherwise, the product won’t be created. ' type: object required: - playbook - price_format - price_type - default_discount - name properties: playbook: type: string description: The name of the playbook where this rule should be evaluated. name: type: string maxLength: 256 description: The name of the pricing rule. rule: type: string maxLength: 4096 description: 'The business condition for ADVANCED price format. Mandatory if price_format: ADVANCED.' price: type: string maxLength: 4096 description: The price amount or formula. Mandatory if price_type is SOLID or ITEM. price_format: type: string enum: - BASIC - ADVANCED description: 'During quotation, the system evaluates pricing_rules according to the product’s pricing configuration, specifically the advanced flag defined in products_pricing.
If advanced: false, the CPQ engine will **only evaluate rules with** price_format: BASIC. Any rules in the pricing_rules list defined with price_format: ADVANCED will be ignored, even if multiple such rules are provided.
In other words, when advanced pricing is disabled at the product level, all ADVANCED pricing rules are excluded from the quotation flow.' price_type: description: 'This field defines the price calculation type.

Available values:

• SOLID
Fixed price value.

• ITEM
Price is based on another SKU in the catalog.
Format of the price field:
<BASE_SKU>;%;<PERCENTAGE_OF_BASE_PRICE>
Example:
"price": "SKU1;%;90"
Result: 90% of SKU1 price.

• GROUP
Price is based on products in the proposal that have specific catalog tag(s).
Format of the price field:
<LIST_OF_TAGS>;<PERCENTAGE_OF_BASE_PRICE>;<WHICH_PRICE_TO_USE>;<HOW_TO_USE_PRICE>;
Example:
"price": "SUPPORT,SW;50;BOTH;AS_IS;"
Result: 50% of products tagged SUPPORT or SW.

• FROM_ALL_QUOTE
Price is based on all other products in the proposal.
Format of the price field:
<PERCENTAGE_OF_OTHER_PRODUCTS_PRICE>
Example:
"price": "10"
Result: 10% of the total price of all other products.

• NEGATIVE
Used for negative price products (e.g., discounts). The price value must be negative.

• GROUP_NEGATIVE
Negative price based on products in the proposal with specific catalog tag(s). By default, only negative products with the specified tags are considered. To include positive products, set "include_positive": true.
Format of the price field:
<LIST_OF_TAGS>;<PERCENTAGE_OF_BASE_PRICE>;<WHICH_PRICE_TO_USE>;<HOW_TO_USE_PRICE>;
Example:
"price": "SUN,FF5;30;NET;AS_IS;"
Result: 30% of negative products tagged SUN or FF5.

• ERP
Price is retrieved from a third-party ERP system during proposal configuration.' type: string enum: - SOLID - FROM_ALL_QUOTE - ITEM - GROUP - NEGATIVE - GROUP_NEGATIVE - ERP currency: type: string description: This field defines how the price value in the pricing rule should be interpreted, especially for tenant accounts configured with multiple currencies.

Available values:

• EXCHANGE_RATE (default)
Use when the price represents the MSRP in the default account currency. The amount will be converted to the proposal currency configured in CPQ.

• NO_EXCHANGE_RATE
Use when the system should treat the price as an absolute value, without performing any currency conversion.

• <ISO-4217 code>
Use when a specific currency is explicitly defined for the price and no currency exchange should be performed (e.g., USD, EUR, BRL).

If null or an empty string is provided, the system treats it as EXCHANGE_RATE. If the price is defined in the default account currency, this field may be null. dynamic_price: type: boolean default: false description: Specifies if a seller is allowed to overwrite the list price during proposal configuration. Not applicable when `price_type` is `ERP` or `ITEM`. rounding_policy: type: string description: 'This field defines the ID of the rounding policy explicitly associated with the pricing rule. It is relevant only when a non-default rounding policy must be applied.

Default: null.

If a value is provided (not null), the following conditions must be met:
1. The account flag enable_rounding_policy must be set to true.
2. The price_item_type must be ADVANCED.
3. The price_item_currency must not be NO_EXCHANGE_RATE.
4. The value must reference an existing rounding policy ID in the system.

If any of these conditions are not satisfied, the rounding policy will not be applied.' max_discount: type: integer minimum: 0 maximum: 100 description: Maximum allowed discount percentage. default_discount: type: integer minimum: 0 maximum: 100 description: Default discount percentage. apply_to: type: string enum: - ASSIGNMENT_RULES - GENERATED_ITEMS default: GENERATED_ITEMS description: Specifies if the rule applies to all assignments or specific ones. apply_to_templates: type: string description: Comma-separated list of assignment template names for which this pricing rule should be evaluated. Relevant when `apply_to` is `ASSIGNMENT_RULES`. apply_to_rules: type: string description: Comma-separated list of assignment rule names for which this pricing rule should be evaluated. Relevant when `apply_to` is `ASSIGNMENT_RULES`. level: type: integer enum: - 0 - 1 - 2 default: 0 description: The level to be included in the price calculation. note: type: string maxLength: 4096 description: A free text note for the rule. based_of_tags: type: string description: 'This field specifies the catalog tags used as the baseline for price calculation. The system will sum the prices of products in the proposal that contain the specified tags and use that total as the base amount to calculate the price of the current product.

Value format: comma-separated list of tags.

This field must be provided when price_type is GROUP or GROUP_NEGATIVE.' based_of_price: type: string enum: - UNIT - NET - LIST - BOTH - USER - MSRP description: 'Specifies which price of the referenced product(s) (matched by based_on_tags) should be used as the base amount for tag-based price calculations.

When price_type is GROUP, valid values are: UNIT, NET, LIST, BOTH, USER, MSRP.

When price_type is GROUP_NEGATIVE, valid values are: NET, LIST.' limit_type: type: string enum: - MIN - MAX - AS_IS - RANGE description: The limit type for tag-based prices. Required if price_type is GROUP or GROUP_NEGATIVE. limit_min_value: type: number description: The minimum limit value for tag-based prices. Required if limit_type is MIN or RANGE. limit_max_value: type: number description: The maximum limit value for tag-based prices. Required if limit_type is MAX or RANGE. disable_rounding: type: boolean description: Specifies if rounding for the price should be disabled. include_positive: type: boolean description: Applicable only when price_type is GROUP_NEGATIVE. Determines whether products with positive prices should also be included in the base amount calculation for the current rule. By default, only products with negative prices (matched by the specified tags) are included. When set to true, both positive- and negative-priced products are considered in the calculation. volume_discount: $ref: '#/components/schemas/VolumeDiscount' ProductPricingProduct: type: object required: - pricing_rules properties: advanced: type: boolean default: false description: Set to `true` for advanced pricing policy, `false` for basic.
When you set `advanced` to `true`, the `pricing_rules.name is required. pricing_rules: type: array description: 'List of the product pricing rules. The order of the elements determines the sequence in which they are evaluated. If `advanced` is `false`, the list must contain exactly one rule with `price_format: BASIC` — if not provided, a default rule with price `0` is created; if more than one `BASIC` rule is provided, only the first is used. If `advanced` is `true`, the list must contain at least one rule with `price_format: ADVANCED`; otherwise the product will not be created.' items: $ref: '#/components/schemas/PricingRuleProduct' ProductPricing: type: object required: - pricing_rules properties: advanced: type: boolean default: false description: Set to `true` for advanced pricing policy, `false` for basic. pricing_rules: type: array description: 'List of the bundle pricing rules. The order of the elements determines the sequence in which they are evaluated. If `advanced` is `false`, the list must contain exactly one rule with `price_format: BASIC` — if not provided, a default rule with price `0` is created; if more than one `BASIC` rule is provided, only the first is used. If `advanced` is `true`, the list must contain at least one rule with `price_format: ADVANCED`; otherwise the bundle will not be created.' items: $ref: '#/components/schemas/PricingRuleProduct' AssignmentRuleProduct: type: object required: - name - rule - product_factors properties: ordinal: type: integer description: The order in which the rule is evaluated. name: type: string maxLength: 200 description: The name of the assignment rule. Must be unique in the context of this SKU. If an empty value is provided, the system will use the `ordinal` value as the rule name. rule: type: string maxLength: 2048 default: 'false' description: The business condition that should trigger the rule. Send `null` if `assignment` is `NEVER`. note: type: string maxLength: 4096 description: A free text note. product_factors: type: array items: $ref: '#/components/schemas/ProductFactor' maxItems: 4 description: 'The list of available product factors configured in the context of the current assignment rule. At least one factor must have `applicable: true` with an explicit `value` defined; otherwise the rule creation will fail.' proposal_attributes: type: array items: $ref: '#/components/schemas/ProposalAttribute' description: 'The list of available proposal attributes configured in the context of the current assignment rule. If not specified, all proposal attributes will be treated as `applicable: true` and will receive an empty value.' AssignmentRule: type: object required: - name - rule - product_factors properties: ordinal: type: integer description: The order in which the rule is evaluated. name: type: string maxLength: 200 description: The name of the assignment rule. Must be unique in the context of this SKU. If an empty value is provided, the system will use the `ordinal` value as the rule name. rule: type: string maxLength: 2048 default: 'false' description: The business condition that should trigger the rule. Send `null` if `assignment` is `NEVER`. note: type: string maxLength: 4096 description: A free text note. product_factors: type: array items: $ref: '#/components/schemas/ProductFactor' maxItems: 4 description: 'The list of available product factors configured in the context of the current assignment rule. At least one factor must have `applicable: true` with an explicit `value` defined; otherwise the rule creation will fail.' proposal_attributes: type: array items: $ref: '#/components/schemas/ProposalAttribute' description: 'The list of available proposal attributes configured in the context of the current assignment rule. If not specified, all proposal attributes will be treated as `applicable: true` and will receive an empty value.' ProductAssignment: type: object required: - playbook properties: assignment: type: string enum: - RULE_BASED - ALWAYS - NEVER default: NEVER description: Directive for the product assignment. At least one rule must be provided in `assignment_rules` when this value is `RULE_BASED` or `ALWAYS`; otherwise the SKU creation will fail. playbook: type: string description: The name of the existing playbook to which the assignment rules are meant to be applied. assignment_rules: type: array description: List of assignment rules. The order of the elements in this list determines the sequence in which the rules are evaluated by the CPQ system. Must be an empty list if `assignment` is `NEVER`. items: $ref: '#/components/schemas/AssignmentRuleProduct' assignment_templates: type: array readOnly: true items: type: string BundleAssignment: type: object required: - playbook properties: assignment: type: string enum: - RULE_BASED - ALWAYS - NEVER default: NEVER description: Directive for the bundle assignment. At least one rule must be provided in `assignment_rules` when this value is `RULE_BASED` or `ALWAYS`; otherwise the SKU creation will fail. playbook: type: string description: The name of the existing playbook to which the assignment rules are meant to be applied. assignment_rules: type: array description: List of assignment rules. The order of the elements in this list determines the sequence in which the rules are evaluated by the CPQ system. Must be an empty list if `assignment` is `NEVER`. items: $ref: '#/components/schemas/AssignmentRule' assignment_templates: type: array readOnly: true items: type: string ConditionalName: type: object required: - playbook properties: playbook: type: string description: The name of the playbook. ordinal: type: integer description: 'The order in which the system evaluates the conditional name rules. For example, the rule with `ordinal: 0` is evaluated first.' rule: type: string maxLength: 2048 description: The business condition that the system should evaluate. name: type: string maxLength: 400 description: The name to be assigned to the specific product instance when the business condition (rule) evaluates to `true`. description: type: string maxLength: 8192 description: The description to be assigned to the specific product instance when the business condition (rule) evaluates to `true`. InheritedAttribute: type: object properties: name: type: string description: The name of the proposal attribute. inherit: type: boolean description: Set to true to inherit the value from the bundle attribute. BundleItem: type: object required: - sku properties: sku: type: string description: The unique identifier of the product in the catalog. ordinal: type: integer default: 0 description: The order of the product in the bundle. how_to_add: type: string enum: - AUTOMATIC - MANUAL - COMBINED description: Specifies how the product should be managed within the bundle during proposal configuration. For `FIXED_PRICE` bundles, only `AUTOMATIC` is valid. For `PRODUCT_SUMMARY` bundles, valid values are `AUTOMATIC`, `MANUAL`, and `COMBINED`. enable_modify_factors: type: boolean description: Specifies if the seller is allowed to modify bundled product factors (e.g. quantity, duration). Relevant for `PRODUCT_SUMMARY` bundles only. product_factors: type: array description: The list of product factors configured for this product in the context of the current bundle. items: $ref: '#/components/schemas/ProductFactor' inherit_proposal_attributes: type: array items: $ref: '#/components/schemas/InheritedAttribute' description: List of attributes that should inherit their value from the parent bundle. ProductCatalogItem: type: object required: - sku - name - product_assignments properties: sku: type: string maxLength: 200 description: The unique identifier of the product in the catalog. name: type: string maxLength: 400 description: The product name. description: type: string maxLength: 21844 description: The product description. tags: type: array description: List of tags associated with the specific product. items: type: string maxLength: 200 primary_tag: type: string maxLength: 200 description: Primary tag of the specific product. merge_products: type: boolean default: false description: Identifies if multiple instances of this product should be merged into a single line during proposal configuration. product_attributes: type: object description: List of product attributes with their respective values. Note that product attributes must be declared in the CPQ version. Use ‘;’ as a delimiter for product attribute type TEXT_LIST. additionalProperties: $ref: '#/components/schemas/ProductAttribute' product_assignments: type: array description: List of product assignment rules defined for the product. The structure of each element in the list is defined in the product_assignments Structure section. items: $ref: '#/components/schemas/ProductAssignment' product_pricing: description: 'List of pricing definitions for the specific SKU. Note: if no pricing is configured for a specific SKU, the system will not instantiate an instance of that product (i.e., a line item) during the proposal configuration process, even if the assignment rule matches the business conditions. Can be an empty list if `assignment` is `NEVER`.' $ref: '#/components/schemas/ProductPricingProduct' product_conditional_names: type: array description: List of ‘conditional name’ rules for the specific SKU. The structure of each element in the list is defined in the product_conditional_names Structure section. items: $ref: '#/components/schemas/ConditionalName' BundleCatalogItem: type: object required: - sku - name - product_assignments - bundle_items properties: sku: type: string maxLength: 200 description: The unique identifier of the bundle in the catalog. name: type: string maxLength: 400 description: The bundle name. description: type: string maxLength: 21844 description: The bundle description. tags: type: array description: List of tags associated with the specific bundle. Use ';' as a delimiter between tags. items: type: string maxLength: 200 primary_tag: type: string maxLength: 200 description: Primary tag of the specific bundle. product_attributes: type: object description: 'List of bundle attributes and their values. Each entry is a key-value pair formatted as `"": { "value": "" }`. Use '';'' as a delimiter for attribute type TEXT_LIST. Attribute names must not exceed 50 characters and attribute values must not exceed 2000 characters.' additionalProperties: $ref: '#/components/schemas/ProductAttribute' product_assignments: type: array description: List of bundle assignment rules defined for the bundle. The structure of each element in the list is defined in the product_assignments Structure section. items: $ref: '#/components/schemas/BundleAssignment' product_pricing: description: List of pricing definitions for the specific SKU. The structure of each element in the list is defined in the product_pricing Structure section. $ref: '#/components/schemas/ProductPricing' product_conditional_names: type: array description: List of the product conditional names. The structure of each element in the list is defined in the product_conditional_names Structure section. items: $ref: '#/components/schemas/ConditionalName' bundle_type: type: string description: The type of the bundle. enum: - FIXED_PRICE - PRODUCT_SUMMARY default: PRODUCT_SUMMARY price_in_bundle_is_zero: type: boolean description: This field determines whether the price of bundled products (aka items within the bundle) should be displayed in the proposal as $0. default: false sync_to_crm: type: boolean description: This field specifies if the bundle should be synchronized to CRM. default: false sync_bundle_price: type: boolean description: Determines how the bundle price should be synchronized to CRM. Set to `true` to synchronize the price at the bundle level. Set to `false` to synchronize the price at the bundled items level — in this case, the bundle price will be synced as 0. default: false bundle_items: type: array description: List of the products included into the bundle. The structure of each element in the list is defined in the bundle_items Structure section. items: $ref: '#/components/schemas/BundleItem' 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. ProductCatalogGetResponse: type: object properties: info: description: Basic information about returned payload $ref: '#/components/schemas/Info' products: type: array description: 'List of products matching specified criteria. Each element in the list contains the following information:' items: $ref: '#/components/schemas/ProductCatalogItem' bundles: type: array description: 'List of bundles matching specified criteria. Each element in the list contains the following information:' items: $ref: '#/components/schemas/BundleCatalogItem' ProductCatalogPostRequest: type: object properties: products: type: array description: 'List of products that should be created in the products catalog. Each element in the list contains the following information:' items: $ref: '#/components/schemas/ProductCatalogItem' bundles: type: array description: 'List of bundles that should be created in the products catalog. Each element in the list contains the following information:' items: $ref: '#/components/schemas/BundleCatalogItem' ProductCatalogPatchProduct: type: object description: Represents an existing product whose data elements should be updated. Only `sku` is required. Include only the data categories (`product_attributes`, `product_assignments`, `product_pricing`) that should be updated; omitted categories are left untouched. required: - sku properties: sku: type: string maxLength: 200 description: The unique identifier of an existing product in the catalog. product_attributes: type: object description: 'Product attributes to update. Each entry is a key-value pair formatted as `"": { "value": "" }`. Attribute names must not exceed 50 characters; attribute values must not exceed 2000 characters. Use `;` as a delimiter for `TEXT_LIST` attribute types. Attributes must be pre-declared in the CPQ version.' additionalProperties: $ref: '#/components/schemas/ProductAttribute' product_assignments: type: array description: Assignment rules to update for this product. The structure of each element is the same as in the POST endpoint. If `assignment` is `RULE_BASED` or `ALWAYS`, at least one rule must be provided. items: $ref: '#/components/schemas/ProductAssignment' product_pricing: description: Pricing definitions to update for this product. Can be an empty list if `assignment` is `NEVER`. $ref: '#/components/schemas/ProductPricingProduct' ProductCatalogPatchBundle: type: object description: Represents an existing bundle whose data elements should be updated. Only `sku` is required. Include only the data categories (`product_attributes`, `product_assignments`, `product_pricing`, `bundle_items`) that should be updated; omitted categories are left untouched. required: - sku properties: sku: type: string maxLength: 200 description: The unique identifier of an existing bundle in the catalog. product_attributes: type: object description: 'Bundle attributes to update. Each entry is a key-value pair formatted as `"": { "value": "" }`. Attribute names must not exceed 50 characters; attribute values must not exceed 2000 characters. Use `;` as a delimiter for `TEXT_LIST` attribute types.' additionalProperties: $ref: '#/components/schemas/ProductAttribute' product_assignments: type: array description: Assignment rules to update for this bundle. If `assignment` is `RULE_BASED` or `ALWAYS`, at least one rule must be provided. items: $ref: '#/components/schemas/BundleAssignment' product_pricing: description: Pricing definitions to update for this bundle. Can be an empty list if `assignment` is `NEVER`. $ref: '#/components/schemas/ProductPricing' bundle_items: type: array description: Products to update within this bundle. Each referenced SKU must already exist in the catalog. items: $ref: '#/components/schemas/BundleItem' ProductCatalogPatchRequest: type: object description: Request body for the PATCH product catalog endpoint. Include only the products and/or bundles whose data elements should be updated. properties: products: type: array description: List of existing products whose data elements should be updated. Each element must reference an existing SKU in the catalog. items: $ref: '#/components/schemas/ProductCatalogPatchProduct' bundles: type: array description: List of existing bundles whose data elements should be updated. Each element must reference an existing bundle SKU in the catalog. items: $ref: '#/components/schemas/ProductCatalogPatchBundle' RequestStatus: type: object properties: request_id: type: string description: ID of the asynchronous request. status: type: string enum: - in-progress - done - failed - queued description: Status of the asynchronous request. error_description: type: string description: Description of the error if the status is 'failed'. error_code: type: string description: Code of the error if the status is 'failed'. RequestSummary: type: object properties: success_count: type: integer description: The number of successfully processed records. errors_count: type: integer description: The number of records that could not be processed. warnings: type: array items: type: string description: List of warnings that occurred during execution. errors: type: array items: type: string description: List of errors that occurred during execution. RequestSummaryResponse: type: object properties: status: type: string enum: - In Progress - Completed - Error description: The status of the asynchronous request. summary: $ref: '#/components/schemas/RequestSummary' PlaybookSyncSettings: type: object properties: enabled: type: string description: 'Sync configuration mode. Valid values: `ALWAYS`, `RULE_BASED`, `DISABLED`.' based_on: type: string nullable: true description: Question ID used for the rule. Returns `null` when no rule applies. PlaybookMetadata: type: object properties: name: type: string description: Internal playbook name. display: type: string description: Playbook display name. document_type: type: array items: type: string enum: - PDF - WORD - EXCEL - DEALROOM description: List of allowed proposal document types. geo_factors_settings: type: boolean description: Enables geo factor logic. present_proposal_summary: type: boolean description: Shows the proposal summary. enable_partner_support: type: boolean description: Indicates whether partner support is enabled. sync_docs_settings: allOf: - $ref: '#/components/schemas/PlaybookSyncSettings' description: Sync docs configuration. sync_products_settings: allOf: - $ref: '#/components/schemas/PlaybookSyncSettings' description: Sync products configuration. PlaybookQuestion: type: object properties: question_id: type: string description: Unique question ID. question: type: string description: Question label/text. question_type: type: string description: 'Type of question. Valid values: `text`, `text_list`, `numeric`, `date`.' answers: type: string description: Possible answers, separated by a semicolon. default_answer: type: string nullable: true description: Default answer used for API template generation. PlaybookGroup: type: object properties: group_id: type: string description: Unique group identifier. group_name: type: string description: Display name of the group. group_type: type: string enum: - QUESTIONS_GROUP - REPEATABLE_GROUP description: Group type. group_external_object: type: string nullable: true description: External object reference. question_data: type: array items: $ref: '#/components/schemas/PlaybookQuestion' description: List of questions in the group. PlaybookExportResponse: type: object properties: playbook_metadata: allOf: - $ref: '#/components/schemas/PlaybookMetadata' description: Playbook configuration metadata. playbook_data: type: array items: $ref: '#/components/schemas/PlaybookGroup' description: List of question groups in the Playbook. QuoteTemplatePartnerProgram: type: object properties: partner_level_name: type: string description: Partner level name. program_name: type: string description: Partner program name. QuoteTemplateQuoteData: type: object properties: group_id: type: string maxLength: 50 description: DealHub group ID. Required for each group in `quote_data`. questions: type: array items: type: object additionalProperties: type: string description: Keys are `question_id`, values are answers. Multi-select answers use the `;` delimiter. description: Required. List of question answers. The template uses the default answer or the first answer for each question. QuoteTemplatePartnerProgramData: type: object description: Partner program-specific discounts. properties: partner_program_name: type: string maxLength: 200 description: Partner program name. partner_level_item_price: type: number format: double description: Partner level item price. partner_level_item_discount: type: number format: double description: Partner level item discount. QuoteTemplateLineItem: type: object properties: sku: type: string description: Required. Product catalog identifier. Must exist in the DealHub catalog. item_name: type: string maxLength: 400 description: Optional. Catalog product name. bundle_ref_sku: type: string description: Conditionally required. Bundle SKU reference. Required if part of a bundle; empty for the bundle product itself. bundle_ref_id: type: integer description: Conditionally required. Unique bundle instance ID. Required for items within a bundle and for the bundle itself. list_price: type: number format: double description: Required. List price. Positive or negative. net_price_per_unit: type: number format: double description: Optional. Net price per unit. net_price: type: number format: double description: 'Required. Total net price: net per unit multiplied by product factors.' msrp: type: number format: double description: Required. Line item MSRP. Positive or negative. msrp_discount: type: number format: double description: Required. Discount applied to MSRP. Positive or negative. sales_discount: type: number format: double description: Required. Sales discount. Positive or negative. total_discount: type: number format: double description: Required. Total discount. Positive or negative. product_factors: type: object additionalProperties: true description: Required. Product-specific factors (quantity, duration) as key-value pairs. attributes: type: object additionalProperties: true description: Optional. Line-item-specific proposal attributes as key-value pairs. partner_program_data: type: array items: $ref: '#/components/schemas/QuoteTemplatePartnerProgramData' description: Optional. Partner program-specific discounts. GenerateQuoteTemplateResponse: type: object description: Preformatted JSON template for the Generate Quote API, based on the Playbook structure. properties: external_opportunity_id: type: string maxLength: 50 description: Required. CRM opportunity ID. Required in all requests. request_action: type: string enum: - draft - submit - publish - sign_externally description: Required. Action for the quote. Enum, lowercase. line_item_details: type: string enum: - basic - all default: basic description: Optional. Level of line item detail. `basic` includes SKU, bundle_ref, name, net price, list price, total discount, and product_factors. playbook: type: string maxLength: 50 description: Optional. Unique name of the playbook (UTF-8). If missing, the system uses the first API-type playbook. quote_name: type: string maxLength: 250 description: Optional. Quote or proposal name. The system default applies if missing; an error occurs if no default exists. dealroom_publish_name: type: string maxLength: 250 description: Optional. DealRoom publish name. The system default applies if missing; an error occurs if no default exists. total_sales_discount: type: number format: double description: Optional. Total discount for all line items. Overrides individual line item discounts if provided. expiration_date: type: string description: Optional. Quote expiration date as a Unix timestamp in milliseconds (GMT). Must not be in the past; the system default applies if missing. document_type: type: string enum: - DealRoom - PDF - WORD - EXCEL description: Required. Type of document. timezone_offset: type: number minimum: -12 maximum: 14 default: 0 description: Optional. Timezone offset from GMT. partner_program: type: array items: $ref: '#/components/schemas/QuoteTemplatePartnerProgram' description: Optional. Selected partner programs. quote_data: type: array items: $ref: '#/components/schemas/QuoteTemplateQuoteData' description: Required. List of question groups and answers. line_items: type: array items: $ref: '#/components/schemas/QuoteTemplateLineItem' description: Optional. List of line items. sign_externally_comment: type: string maxLength: 1000 description: Conditionally required. Comment for external signing. Required if `request_action` = `sign_externally`. PlaybookErrorResponse: type: object properties: error: type: string description: Error message. code: type: integer description: HTTP status code.