Beacon Rest Services V3 (Public / Integrations)

servers:
  - url: https://beaconproplus.com/v3/rest/com/becn
    description: >-
      Production. Added by API Evangelist; the harvested document carried no servers[].
      Source: info.description of the all_api spec: 'Version 3: https://beaconproplus.com/v3/rest/com/becn'; probed 2026-09-04 -> 401 JSON envelope
openapi: 3.0.0
info:
  title: Beacon Rest Services Ver 3 (Public)
  version: release/7.2_siteId
  description: |
    This version of APIs do not require the user to login, to be able to access
    services. A bearer token is required to be authorized to access the
    services.

    [ PROD BASE URL: *https://beaconproplus.com/v3/rest/com/becn* ]

    [ UAT  BASE URL: *https://beacon-uat.becn.com/v3/rest/com/becn* ]

    [ DEV  BASE URL: *https://beacon-dev.becn.com/v3/rest/com/becn* ]

    ### API Site ID:
    <details>
      <summary>Show...</summary>
      Most of the APIs supports the `apiSiteId` parameter in the following locations, the parsing priority is higher to lower. For example, if this parameter appears both in request parameter and request body, will get the one in the request parameter, any other locations will be ignored.
      1. `apiSiteId` in Request Parameter/URL/Query String e.g.
          ```
          example.com/?apiSiteId=XYZ...
          example.com/?...&apiSiteId=XYZ...
          ```
      2. `apiSiteId` in Request Body/Payload e.g.
    
          ```
          {
            ...
            "apiSiteId": "XYZ",
            ...
          }
          ```
    
          Please be noted, only support when `apiSiteId` is the root element of request body. For example, the `apiSiteId` in the following request body is the second element, so this property will be ignored:
          ```
          {
            ...
            "foo": {
              "apiSiteId": "XYZ",
            }
            ...
          }
          ```
      3. `apiSiteId` related OAuth Token in Request Header e.g.
          ```
          Authorization Bearer atdy9au5qtg0ofkxdewwr3169...
          ```
          In this case, the `apiSiteId` will be parsed via the OAuth Token. For example, if one token is generated by the client id 'nigu0zjtyih7lb36l2...', then this client related api site id(pre-defined and stored in the server database) will be the value of `apiSiteId`
    </details>
components:
  schemas:
    categoryObj:
      type: object
      properties:
        categoryName:
          type: string
        categoryId:
          type: string
        facetId:
          type: string
    categoryObj2:
      type: object
      properties:
        categoryName:
          type: string
        categoryId:
          type: string
        recordCount:
          type: integer
          example: 32
        facetId:
          type: string
    productObj_itemlist:
      type: object
      properties:
        productImage:
          type: string
        productOnErrorImage:
          type: string
        productAdditionalOnErrorImage:
          type: string
        longDesc:
          type: string
        brand:
          type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/categoryObj'
        shortDesc:
          type: string
        productName:
          type: string
        productId:
          type: string
        baseProductName:
          type: string
        internalProductName:
          type: string
        url:
          type: string
        skuList:
          type: array
          items:
            $ref: '#/components/schemas/skuListObj_itemlist'
    productObj_itemDetails:
      type: object
      properties:
        productImage:
          type: string
        productOnErrorImage:
          type: string
        productAdditionalOnErrorImage:
          type: string
        longDesc:
          type: string
        manufactureNumber:
          type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/categoryObj'
        shortDesc:
          type: string
        itemNumber:
          type: string
        productName:
          type: string
        productId:
          type: string
        baseProductName:
          type: string
        internalProductName:
          type: string
        brand:
          type: string
        url:
          type: string
        relatedProducts:
          type: array
          items:
            $ref: '#/components/schemas/relatedProductsObj'
    relatedProductsObj:
      type: object
      properties:
        productImage:
          type: string
        url:
          type: string
        productName:
          type: string
        productId:
          type: string
        internalProductName:
          type: string
        brand:
          type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/categoryObj'
    skuListObj_itemlist:
      type: object
      properties:
        itemNumber:
          type: string
        productNumber:
          type: string
        itemImage:
          type: string
          example: /images/large/404191_default_hero.jpg
        swatchImage:
          type: string
          example: /images/large/404191_default_swatch.jpg
        skuShortDesc:
          type: string
        manufactureNumber:
          type: string
        variations:
          $ref: '#/components/schemas/PDPskusVariationObj'
        hoverAttributes:
          $ref: '#/components/schemas/hoverAttributesObj'
    hoverAttributesObj:
      type: object
      properties:
        sellingUom:
          type: string
        piecesPerUom:
          type: string
        coverageUom:
          type: string
        ppCoverageUom:
          type: string
        lengthExposure:
          type: string
        widthExposure:
          type: string
        lengthHover:
          type: string
        widthHover:
          type: string
        ncpSellingUom:
          type: string
        gcpSellingUom:
          type: string
        sslvoDimensionIn:
          type: string
        sswhoDimensionOption1In:
          type: string
        sswhoDimensionOption2In:
          type: string
        sswhoDimensionOption3In:
          type: string
        lslvoDimensionIn:
          type: string
        lswhoDimensionIn:
          type: string
        rvlvoDimensionIn:
          type: string
        rvwhoDimensionIn:
          type: string
        nfvaHover:
          type: string
        nfvaUomHover:
          type: string
        fhLapIn:
          type: string
        fvLapIn:
          type: string
        chLapIn:
          type: string
        cvLapIn:
          type: string
        cfmValue:
          type: string
        cfmUom:
          type: string
    currentSkuObj:
      type: object
      properties:
        currentUOM:
          type: string
        manufactureNumber:
          type: string
        unitPrice:
          type: number
          format: double
        itemNumber:
          type: string
        productNumber:
          type: string
        uomlist:
          type: array
          items:
            type: string
        itemImage:
          type: string
        heroImages:
          $ref: '#/components/schemas/heroImagesObj'
        thumbImage:
          type: string
        swatchImage:
          type: string
        skuShortDesc:
          type: string
        auxiliaryImages:
          $ref: '#/components/schemas/auxiliaryImagesObj'
        variations:
          $ref: '#/components/schemas/PDPskusVariationObj'
        hoverAttributes:
          $ref: '#/components/schemas/hoverAttributesObj'
    skuObj:
      type: object
      properties:
        currentUOM:
          type: string
        unitPrice:
          type: number
          format: double
        itemNumber:
          type: string
        productNumber:
          type: string
        itemImage:
          type: string
        thumbImage:
          type: string
        swatchImage:
          type: string
        skuShortDesc:
          type: string
        auxiliaryImages:
          $ref: '#/components/schemas/auxiliaryImagesObj'
        variations:
          $ref: '#/components/schemas/PDPskusVariationObj'
        hoverAttributes:
          $ref: '#/components/schemas/hoverAttributesObj'
    auxiliaryImagesObj:
      type: object
      additionalProperties:
        type: object
      example:
        - image: /images/large/357583_1_thumb.jpg
        - image: /images/large/357583_2_thumb.jpg
        - image: /video/Video_Demo.mp4
          videoUrl: /images/default_video.jpg
    heroImagesObj:
      type: object
      additionalProperties:
        type: object
      example:
        - image: /images/large/357583_default_hero.jpg
        - image: /images/large/357583_1_hero.jpg
        - image: /images/large/357583_2_hero.jpg
    facetObj:
      type: object
      properties:
        facetId:
          type: string
        facetName:
          type: string
        recordCount:
          type: integer
          example: 32
        selected:
          type: boolean
    didYouMeanAndAutoCorrectionObj:
      type: object
      properties:
        message:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              filter:
                type: string
    itemlistRep:
      type: object
      properties:
        message:
          type: string
        totalNumRecs:
          type: integer
        pageNumRecs:
          type: integer
        didYouMean:
          $ref: '#/components/schemas/didYouMeanAndAutoCorrectionObj'
        autoCorrection:
          $ref: '#/components/schemas/didYouMeanAndAutoCorrectionObj'
        items:
          type: array
          items:
            $ref: '#/components/schemas/productObj_itemlist'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/categoryObj2'
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/facetObj'
          example:
            Categories:
              - facetId: '2136008660'
                facetName: Residential Roofing
                selected: false
                children:
                  - facetId: '2136009260'
                    facetName: Residential Accessories
                    recordCount: 216
                    selected: true
                    children:
                      - facetId: '2136009261'
                        facetName: 'Adhesives, Caulk, & Sealants'
                        recordCount: 1
                        selected: false
                      - facetId: '2136009263'
                        facetName: Fasteners
                        recordCount: 1
                        selected: false
                      - facetId: '2136009269'
                        facetName: Flashings
                        recordCount: 1
                        selected: false
            Color:
              - facetId: '4294967258'
                facetName: Grey
                recordCount: 15
                selected: false
              - facetId: '4294967259'
                facetName: Blue
                recordCount: 23
                selected: false
            Product Style:
              - facetId: '4294967260'
                facetName: R-11
                recordCount: 54
                selected: true
              - facetId: '4294967261'
                facetName: R-13
                recordCount: 785
                selected: true
              - facetId: '4294967262'
                facetName: R-15
                recordCount: 642
                selected: false
            Brand:
              - facetId: '4294967263'
                facetName: Johns Manville
                recordCount: 54
                selected: true
              - facetId: '4294967264'
                facetName: Owens Corning
                recordCount: 2354
                selected: false
    productsRep:
      type: object
      properties:
        result:
          type: object
          properties:
            products:
              type: array
              items:
                $ref: '#/components/schemas/productObj_mincronMapping'
            pagination:
              $ref: '#/components/schemas/BCPaginationDataObj'
    BCPaginationDataObj:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/BCOtherPaginationObj'
        previous:
          $ref: '#/components/schemas/BCOtherPaginationObj'
        pageSize:
          type: integer
        currentPage:
          type: integer
        totalCount:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/BCPaginationObj'
    BCOtherPaginationObj:
      type: object
      properties:
        available:
          type: boolean
        label:
          type: string
        page:
          type: integer
    BCPaginationObj:
      type: object
      properties:
        enable:
          type: boolean
        page:
          type: integer
        currentPage:
          type: boolean
        type:
          type: string
    productObj_mincronMapping:
      type: object
      properties:
        customerNumber:
          type: string
        itemNumber:
          type: string
        itemDescription:
          type: string
        productNumber:
          type: string
        aliasNumber:
          type: string
    itemDetailsRep:
      type: object
      properties:
        product:
          $ref: '#/components/schemas/productObj_itemDetails'
        message:
          type: string
        specification:
          type: object
          additionalProperties:
            type: string
          example:
            Shingles_Per_Square: '80,'
            Algae_Resistance: '10 years,'
            Coverage_Per_Square: '100 sq. ft,'
            Bundles_Per_Square: '3,'
            Nominal_Size: '12\x36\,'
            Net_Free_Vent_Area__NFVA_: 'Vent Area,'
            Exposure: '5\,'
            Wind_Resistance: 60mph
        resource:
          type: object
          additionalProperties:
            type: string
          example:
            General Instructrions: 'http://www.xxx.com/download.php,'
            Warranty: 'http://www.xxx.com/download.php,'
            MSDS: 'http://www.xxx.com/download.php,'
            Brochure: 'http://www.xxx.com/download.php,'
        currentSKU:
          $ref: '#/components/schemas/currentSkuObj'
        skuList:
          type: array
          items:
            $ref: '#/components/schemas/skuObj'
        variations:
          $ref: '#/components/schemas/variationsObj'
    variationsObj:
      type: object
      additionalProperties:
        type: object
      example:
        color:
          White:
            - '100001'
            - '200002'
          Dover:
            - '100001'
            - '300003'
        size:
          12x10:
            - '100001'
          4x4:
            - '200002'
            - '300003'
        thickness:
          2mm:
            - '100001'
          4mm:
            - '200002'
          6mm:
            - '300003'
    PDPskusVariationObj:
      type: object
      additionalProperties:
        type: object
      example:
        color:
          - White
          - Dover
        size:
          - 12x10
        thickness:
          - 2mm
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
paths:
  /itemlist:
    get:
      security:
        - bearerAuth: []
      tags:
        - Catalog ITEM Services
      summary: Get list of items
      description: >-
        This service will list all the products for selected account, based on
        availability.

      parameters:
        - in: query
          name: accountId
          schema:
            type: string
          description: Account ID
          required: false
        - in: query
          name: pageSize
          description: Default page size is 21. Max Page Size can be configured in BCC, maxPageSize default value is 30.
            If pageSize exceeds maxPageSize, the amount of maxPageSize items return.
          schema:
            type: integer
            format: int32
        - in: query
          name: pageNo
          description: 'Default page no is 1, the first page'
          schema:
            type: integer
            format: int32
        - in: query
          name: filter
          description: |
            Search terms

            This parameter also support the following syntax:

            * `productId:ID1,ID2...IDn`
              * Filter by given product ID list, separated by comma. e.g. "productId:C-010001,C-010002,C-010003"
            * `companyId:ID1,ID2...IDn`
              * Filter by given Company ID list, separated by comma. e.g. "companyId:1,5,10"
            * `divisionId:ID1,ID2...IDn`
              * Filter by given division ID list, separated by comma. e.g. "divisionId:1,2,10"
            * `productId:ID1,ID2...IDn;companyId:ID1,ID2...IDn`
              * Filter by given product ID and Company ID list, separated by ';' between filter parameter types. e.g. "productId:C-734607,C-123456;companyId:10,5"
          schema:
            type: string
        - in: query
          name: cateFilter
          description: Category search terms
          schema:
            type: string
        - in: query
          name: facetsFilter
          description: >
            Filter syntax:

            * Facets search IDs, separated by comma
              * e.g. "4294965847,4294965836"
            * Indicate which dimension to search, `<facet type>:<facet name>`,
            separated by comma, case insensitive, ignore white space
              * e.g. "size:0ft x 2ft,packaging:100 bag,thickness:102mm,style:A Slop,color: Beige"
            * Special charactors should be URL encoded then append to query
            string
                * e.g. raw: 'facetsFilter=Thickness:20_,Thickness:20",Thickness:20mm,Size:"9 x "12,Size:#12,Size:1! x 1!,Size:1-5/8",Size:10" x 15",Size:100' x 200',Size:2-7/8",Size:6> x 500<'
                * e.g. URL encoded: 'facetsFilter=Thickness%3a20_%2cThickness%3a20%22%2cThickness%3a20mm%2cSize%3a%229+x+%2212%2cSize%3a%2312%2cSize%3a1!+x+1!%2cSize%3a1-5%2f8%22%2cSize%3a10%22+x+15%22%2cSize%3a100%27+x+200%27%2cSize%3a2-7%2f8%22%2cSize%3a6%3e+x+500%3c'
            * The above syntax can be mixed together
              * e.g. "size:0ft x 2ft,4294965847,packaging:100 bag,thickness:102mm,4294965836,style:A Slop,color: Beige"
          schema:
            type: string
        - in: query
          name: showSkuList
          description: 'if "true", display sku list'
          schema:
            type: string
        - in: query
          name: showFacets
          description: 'if "false", do not display facets. Default is "true"'
          schema:
            type: string
        - in: query
          name: enableAutoCorrection
          description: Default is true, will enable auto correction for `filter`
          schema:
            type: string
        - in: query
          name: enableDidYouMean
          description: Default is true, will enable did you mean features for `filter`
          schema:
            type: string
        - in: query
          name: showHoverAttrs
          description: 'if "true", display Hover attributes'
          schema:
            type: string
        - in: query
          name: hoverSearch
          description: 'if "true", display Hover version of search'
          schema:
            type: string
      responses:
        '200':
          description: |
            successful operation

            If failed, return messageCode, refer to messageCode doc.

            Example

            { "messageCode": "1001", "message": "Validation exception" }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/itemlistRep'
        '400':
          description: 'Bad Request, accountId is invalid'
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '500':
          description: Internal exception
  /downloadCatalogItemData:
    get:
      security:
        - bearerAuth: []
      tags:
        - Catalog ITEM Services
      summary: Download catalog item data(include branches, branches skus and skus.)
      description: |
        This service can download catalog item data.
      responses:
        '200':
          content:
            application/zip:
              schema:
                type: string
                format: binary
          description: |
            successful operation

            return the zip file

            Failed operation

            return 'application/json' and refer to *API Uniform Format*
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '403':
          description: 'Forbidden, user do not has permission to access this API'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '419':
          description: 'Unauthorized, the authorization bearer token is expired'
        '500':
          description: Internal exception
  /skuData:
    get:
      security:
        - bearerAuth: []
      tags:
        - Catalog ITEM Services
      summary: Download catalog sku item data
      description: |
        This service can download catalog sku item data.
      parameters:
        - in: query
          name: branchNumber
          schema:
            type: string
          description: Branch Number
          required: false
        - in: query
          name: pageNo
          schema:
            type: string
          description: Page Number, default value is 1
          required: false
        - in: query
          name: pageSize
          schema:
            type: string
          description: Page Size, default value is 1000
          required: false
      responses:
        '200':
          content:
            application/zip:
              schema:
                type: object
                format: binary
          description: |
            successful operation

            return the zip file

            Failed operation

            return 'application/json' and refer to *API Uniform Format*
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '403':
          description: 'Forbidden, user do not has permission to access this API'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '419':
          description: 'Unauthorized, the authorization bearer token is expired'
        '500':
          description: Internal exception
  /branchData:
    get:
      security:
        - bearerAuth: []
      tags:
        - Catalog ITEM Services
      summary: Download catalog branch item data
      description: |
        This service can download catalog branch item data.
      parameters:
        - in: query
          name: pageNo
          schema:
            type: string
          description: Page Number, default value is 1
          required: false
        - in: query
          name: pageSize
          schema:
            type: string
          description: Page Size, default value is 500
          required: false
      responses:
        '200':
          content:
            application/zip:
              schema:
                type: object
                format: binary
          description: |
            successful operation

            return the csv file

            Failed operation

            return 'application/json' and refer to *API Uniform Format*
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '403':
          description: 'Forbidden, user do not has permission to access this API'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '419':
          description: 'Unauthorized, the authorization bearer token is expired'
        '500':
          description: Internal exception
  /productAvailabilityData:
    get:
      security:
        - bearerAuth: []
      tags:
        - Catalog ITEM Services
      summary: Download catalog product availability item data
      description: |
        This service can download catalog product availability item data.
      parameters:
        - in: query
          name: region
          description: Region Number
          required: false
          schema:
            type: string
        - in: query
          name: branchNumber
          description: Branch Number
          required: false
          schema:
            type: string
        - in: query
          name: market
          description: Market Number
          required: false
          schema:
            type: string
        - in: query
          name: pageNo
          schema:
            type: string
          description: Page Number, default value is 1
          required: false
        - in: query
          name: pageSize
          schema:
            type: string
          description: Page Size, default value is 1000
          required: false
      responses:
        '200':
          content:
            application/zip:
              schema:
                type: object
                format: binary
          description: |
            successful operation

            return the zip file

            Failed operation

            return 'application/json' and refer to *API Uniform Format*
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '403':
          description: 'Forbidden, user do not has permission to access this API'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '419':
          description: 'Unauthorized, the authorization bearer token is expired'
        '500':
          description: Internal exception
  /itemDetails:
    get:
      security:
        - bearerAuth: []
      tags:
        - Catalog ITEM Services
      summary: Get items details
      description: This service returns product details based on Product or item Id.
      parameters:
        - in: query
          name: productId
          schema:
            type: string
          description: Product ID
        - in: query
          name: itemNumber
          schema:
            type: string
          description: Item number(SKU ID)
        - in: query
          name: accountId
          description: Account ID
          schema:
            type: string
        - in: query
          name: jobNumber
          schema:
            type: string
          description: Job Number
        - in: query
          name: uom
          schema:
            type: string
          description: Unit of Measure
        - in: query
          name: showHoverAttrs
          description: 'if "true", display hover attributes'
          schema:
            type: string
      responses:
        '200':
          description: |
            successful operation

            If failed, return messageCode, refer to messageCode doc.

            Example

            { "messageCode": "1001", "message": "Validation exception" }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/itemDetailsRep'
        '400':
          description: 'Bad Request, accountId is invalid'
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '500':
          description: Internal exception
  /mincronMapping:
    get:
      security:
        - bearerAuth: []
      tags:
        - Integration Services
      summary: Get Mincron mapping products
      description: This service returns mapping products based on customer number.
      parameters:
        - in: query
          name: accountId
          schema:
            type: string
          description: Customer number
          required: true
        - in: query
          name: pageSize
          description: Default page size is 100
          schema:
            type: integer
        - in: query
          name: pageNo
          description: Default page no is 1
          schema:
            type: integer
      responses:
        '200':
          description: |
            successful operation

            If failed, return messageCode, refer to messageCode doc.

            Example

            { "messageCode": "1001", "message": "Validation exception" }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/productsRep'
        '401':
          description: 'Unauthorized, the authorization bearer token is invalid'
        '403':
          description: 'Forbidden, user do not has permission to access this API'
        '405':
          description: 'Method not allowed, the request method is not valid for this API or this API is not available.'
        '419':
          description: 'Unauthorized, the authorization bearer token is expired'
        '500':
          description: Internal exception
  /deleteAccount:
    post:
      security:
        - bearerAuth: []
      tags:
        - My Account Services
      summary: Delete account
      description: The service returns that the account was successfully deleted and sends the message.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                email:
                  type: string
                phoneNumber:
                  type: string
                accountNumber:
                  type: string
      responses:
        '200':
          description: |
            successful operation

          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: null
                  success:
                    type: boolean
                  messages:
                    type: object
                    properties:
                      code:
                        type: number
                        example: null
                      type:
                        type: string
                        example: "success"
                      value:
                        type: string
                        example: "Delete account successful."
                      key:
                        type: string
                        example: null


        '400':
          description: 'Bad Request, the request method is not valid'
        '401':
          description: 'Unauthorized, user do not login'
        '500':
          description: Internal exception