DealHub Product Catalog API

openapi: 3.2.0
info:
  title: Dealhub Product Catalog API
  version: 1.0.0
  description: 'Operations tagged Product Catalog across 2 of this provider''s published API definitions: dealhub-subskribe-api-openapi.yml, dealhub-version-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.app.subskribe.com
- 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').
tags:
- name: Product Catalog
paths:
  /charges/{chargeId}:
    get:
      tags:
      - Product Catalog
      summary: Get charge details
      description: Gets the details of the specified charge.
      operationId: getCharge
      parameters:
      - name: chargeId
        in: path
        description: id of the charge
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /charges/revrec/csv/download:
    get:
      tags:
      - Product Catalog
      summary: Download revenue recognition fields
      description: Downloads your charge revenue recognition fields as a csv
      operationId: getRevRecFieldsAsCsv
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /charges/revrec/csv:
    post:
      tags:
      - Product Catalog
      summary: Backfill revenue recognition fields
      description: Backfill API to update revenue recognition fields on charges
      operationId: backfillRevRecFields
      parameters:
      - name: isDryRun
        in: query
        required: false
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/uploadApprovalMatrixCSV'
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/charges/{chargeId}/ledgerAccounts:
    get:
      tags:
      - Product Catalog
      summary: Get ledger accounts
      description: Gets the ledger accounts mapped to the specified charge
      operationId: getChargeLedgerAccounts
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      - name: chargeId
        in: path
        description: id of the charge
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LedgerAccount'
      security:
      - ApiKeyAuth: []
    put:
      tags:
      - Product Catalog
      summary: Map ledger accounts
      description: Map ledger accounts to the specified charge for the specified plan.
      operationId: mapLedgerAccountsToCharge
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      - name: chargeId
        in: path
        description: id of the charge
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of the ledger account ids
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LedgerAccount'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/replacedPlans:
    get:
      tags:
      - Product Catalog
      summary: Get replaced plans
      description: ''
      operationId: getReplacedPlans
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans:
    get:
      tags:
      - Product Catalog
      summary: Get plans
      description: Returns all plans for a product. The result is paginated. To retrieve all results pass the cursor returned from a call to the next call until all results are returned.
      operationId: getPlans
      parameters:
      - name: productId
        in: query
        description: id of the product
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: filter by plan status
        required: false
        schema:
          type: string
          enum:
          - DRAFT
          - ACTIVE
          - GRANDFATHERED
          - ARCHIVED
          - DEPRECATED
      - name: cursor
        in: query
        description: cursor from the last call
        required: false
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: number of results per page
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJsonPaginationResponse'
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Product Catalog
      summary: Create a plan
      description: Creates a plan. On success the id of the new plan is returned.
      operationId: addPlan
      requestBody:
        $ref: '#/components/requestBodies/PlanJson'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}:
    get:
      tags:
      - Product Catalog
      summary: Get plan details
      description: Returns the details of the specified plan.
      operationId: getPlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    put:
      tags:
      - Product Catalog
      summary: Update plan
      description: Updates the details of the specified plan. Note you can't update the details of a plan once it's in use.
      operationId: updatePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/PlanJson'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - Product Catalog
      summary: Delete a plan
      description: Deletes a plan. Note you can't delete a plan that's in use.
      operationId: deletePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/terms:
    put:
      tags:
      - Product Catalog
      summary: Update plan terms
      description: Updates predefined terms associated with the specified plan.
      operationId: updatePlanTerms
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: json of the plan details
        required: true
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/metadata:
    put:
      tags:
      - Product Catalog
      summary: Update plan metadata
      description: Update plan metadata. For now, this can be used only to change the entities assigned to a plan
      operationId: updatePlanMetadata
      parameters:
      - name: planId
        in: path
        description: plan id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanMetadataJson'
        description: plan metadata to be updated
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/revertToDraft:
    put:
      tags:
      - Product Catalog
      summary: Revert a plan to draft
      description: Marks a plan as draft
      operationId: deactivatePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/charges:
    post:
      tags:
      - Product Catalog
      summary: Add charge to plan
      description: Adds a charge to the specified plan.  Success response contains ID of the new charge.
      operationId: addCharge
      parameters:
      - name: planId
        in: path
        description: ID of the plan to which you want to add the charge. To get a list of IDs, call the [Get plans](/reference/getplans) operation.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeJson'
        description: JSON representing the charge details
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/charges/{chargeId}/partial:
    put:
      tags:
      - Product Catalog
      summary: Update non-financial charge details
      description: Updates certain details of the specified charge which won't impact its financial treatment
      operationId: patchCharge
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      - name: chargeId
        in: path
        description: id of the charge
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargePartialJson'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/activate:
    put:
      tags:
      - Product Catalog
      summary: Activate a plan
      description: Marks a plan as active
      operationId: activatePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/deprecate:
    put:
      tags:
      - Product Catalog
      summary: Deprecate a plan
      description: Marks a plan as deprecated. Once deprecated a plan may not be attached to new orders.
      operationId: deprecatePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/reactivate:
    put:
      tags:
      - Product Catalog
      summary: Reactivate a plan
      description: Reactivates a deprecated plan.
      operationId: reactivatePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/duplicate:
    post:
      tags:
      - Product Catalog
      summary: Duplicate a plan
      description: Duplicates the specified plan. On success the new plan id is returned.
      operationId: duplicatePlan
      parameters:
      - name: planId
        in: path
        description: id of the plan to duplicate
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/{planId}/charges/{chargeId}:
    put:
      tags:
      - Product Catalog
      summary: Update charge details
      description: Updates the details of the specified charge on the specified plan.
      operationId: updateCharge
      parameters:
      - name: planId
        in: path
        description: id of the plan associated with the charge
        required: true
        schema:
          type: string
      - name: chargeId
        in: path
        description: id of the charge
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeJson'
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - Product Catalog
      summary: Delete a charge
      description: Removes a charge from a plan.
      operationId: deleteCharge
      parameters:
      - name: planId
        in: path
        description: id of the plan
        required: true
        schema:
          type: string
      - name: chargeId
        in: path
        description: id of the charge
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /plans/filter/customField:
    get:
      tags:
      - Product Catalog
      summary: Get Plans that have a specific value for a custom field
      description: Gets Plans that have a specific value for a custom field
      operationId: getPlansFilterByCustomFields
      parameters:
      - name: customFieldName
        in: query
        description: Name of the custom field to filter by
        required: false
        schema:
          type: string
      - name: customFieldValue
        in: query
        description: Value of the custom field to filter by
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlanJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /product/categories/{id}:
    get:
      tags:
      - Product Catalog
      summary: Get product category details
      description: Gets the details of the specified product category
      operationId: getProductCategory
      parameters:
      - name: id
        in: path
        description: id of the category
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCategory'
      security:
      - ApiKeyAuth: []
    put:
      tags:
      - Product Catalog
      summary: Update product category details
      description: Updates the details of a product category
      operationId: updateProductCategory
      parameters:
      - name: id
        in: path
        description: id of the category
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/ProductCategory'
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - Product Catalog
      summary: Delete a product category
      description: Deletes the specified product category. Note that a product category can't be delete once it's in use.
      operationId: deleteProductCategory
      parameters:
      - name: id
        in: path
        description: id of the category
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCategory'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /product/categories:
    get:
      tags:
      - Product Catalog
      summary: Get product Categories
      description: Gets all product categories for your tenant. The results are paginated. To fetch all results pass the cursor returned from a call to the subsequent calls until all results are returned. Initially the cursor should not be specified.
      operationId: getProductCategories
      parameters:
      - name: cursor
        in: query
        description: cursor from prior call
        required: false
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: number of results per page
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCategoryPaginationResponse'
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Product Catalog
      summary: Create a product category
      description: Creates a product category. On success the id of the category is returned.
      operationId: addProductCategory
      requestBody:
        $ref: '#/components/requestBodies/ProductCategory'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCategory'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /products/{id}:
    get:
      tags:
      - Product Catalog
      summary: Get product details
      description: Gets the details of the specified product.
      operationId: getProduct
      parameters:
      - name: id
        in: path
        description: ID of the product
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductJson'
      security:
      - ApiKeyAuth: []
    put:
      tags:
      - Product Catalog
      summary: Update product details
      description: Updates the details of the specified product
      operationId: updateProduct
      parameters:
      - name: id
        in: path
        description: id of the product
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/ProductInputJson'
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - Product Catalog
      summary: Delete a product
      description: Delete the specified product.
      operationId: deleteProduct
      parameters:
      - name: id
        in: path
        description: id of the product
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /products/export:
    get:
      tags:
      - Product Catalog
      summary: Export product catalog
      description: Export the product catalog in CSV format.
      operationId: exportProductCatalog
      responses:
        default:
          description: successful operation
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /products:
    get:
      tags:
      - Product Catalog
      summary: Get products
      description: Returns all products for your tenant. The results on paginated. To fetch them all pass the cursor returned from a call to the subsequent call until all results are fetched. Initially the cursor should not be specified.
      operationId: getProducts
      parameters:
      - name: cursor
        in: query
        description: cursor received from prior call
        required: false
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: number of results per page
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductJsonPaginationResponse'
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Product Catalog
      summary: Create a product
      description: Creates a product for your tenant. The success response contains the ID of the product.
      operationId: addProduct
      requestBody:
        $ref: '#/components/requestBodies/ProductInputJson'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductJson'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.app.subskribe.com
  /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'
      security:
      - bearerAuth: []
    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').
  /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'
      security:
      - bearerAuth: []
    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').
  /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

# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dealhub/refs/heads/main/openapi/dealhub-product-catalog-api-openapi.yml