openapi: 3.0.3
info:
  title: Retailers API
  description: Enables users to fetch retailer information, ratings, performance status and performance KPI score.
  version: 11.0.3
tags:
  - name: Retailer
    description: Enables users to fetch retailer information, ratings, performance status and performance KPI score.
paths:
  '/retailer/retailers/{retailer-id}':
    get:
      summary: Retrieves the retailer information for a retailer.
      description: This endpoint allows retailers to retrieve general retailer information.
      operationId: retailer-information-by-retailer-id
      tags:
        - Retailer
      x-badges:
        - name: 'BETA'
          position: after
          color: "#0000A4"
      x-bol-scopes:
        - retailer
        - retailer-info.read
      parameters:
        - in: path
          name: retailer-id
          description: The ID of the retailer which information belongs to. Use 'current' to retrieve information of the currently authenticated retailer account.
          required: true
          schema:
            $ref: "../common/models.yaml#/components/schemas/retailerId"
      responses:
        '200':
          $ref: "#/components/responses/200_GET_RETAILER_INFO_SUCCESSFUL"
        '400':
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        '403':
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        '404':
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        '500':
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        '503':
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        '504':
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
  '/retailer/retailers/{retailer-id}/ratings':
    get:
      summary: Retrieves the rating information for a retailer.
      description: This endpoint allows retailers to retrieve retailer ratings information.
      operationId: retailer-ratings
      tags:
        - Retailer
      x-badges:
        - name: 'BETA'
          position: after
          color: "#0000A4"
      x-bol-scopes:
        - retailer
        - retailer-info.read
      parameters:
        - in: path
          name: retailer-id
          description: The ID of the retailer which the rating belongs to. Use 'current' to retrieve ratings of the currently authenticated retailer account.
          required: true
          schema:
            $ref: "../common/models.yaml#/components/schemas/retailerId"
      responses:
        '200':
          $ref: "#/components/responses/200_GET_RETAILER_RATINGS_SUCCESSFUL"
        '400':
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        '403':
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        '404':
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        '500':
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        '503':
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        '504':
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
  '/retailer/retailers/performance-status':
    get:
      summary: Retrieves the current performance status for authenticated retailer.
      description: This endpoint allows retailers to retrieve current performance status information.
      operationId: retailer-performance-status
      tags:
        - Retailer
      x-badges:
        - name: 'BETA'
          position: after
          color: "#0000A4"
      x-bol-scopes:
        - retailer
        - retailer-info.read
      responses:
        '200':
          $ref: "#/components/responses/200_GET_PERFORMANCE_STATUS_SUCCESSFUL"
        '400':
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        '403':
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        '500':
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        '503':
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        '504':
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
  '/retailer/retailers/kpi-scores':
    get:
      summary: Retrieves the KPI scores of the current retailer for a given week.
      description: This endpoint allows retailers to retrieve KPI score information.
      operationId: retailer-kpi-scores
      tags:
        - Retailer
      x-badges:
        - name: 'BETA'
          position: after
          color: "#0000A4"
      x-bol-scopes:
        - retailer
        - retailer-info.read
      parameters:
        - name: kpi
          in: query
          description: Service norm name for the score.
          required: true
          example: FULFILMENT
          schema:
            type: string
            enum:
              - CANCELLATIONS
              - CASE_ITEM_RATIO
              - FULFILMENT
              - HANDOVER
              - ON_TIME
              - RESPONSE_TIME
              - RETURNS
              - REVIEWS
              - TRACK_AND_TRACE
        - name: week
          in: query
          description: The week number for which the score is requested in the ISO-8601 format 'YYYY-WW'.
          example: 2025-01
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/200_GET_KPI_SCORE_SUCCESSFUL"
        '400':
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        '403':
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        '500':
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        '503':
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        '504':
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'

components:
  schemas:
    RetailerRatings:
      type: object
      description: Represents the information about the rating method used to obtain ratings, rating themselves and different types of review counts.
      required:
        - ratingMethod
        - retailerRating
        - retailerReview
        - isTopRetailer
      properties:
        ratingMethod:
          $ref: '#/components/schemas/RatingMethod'
        retailerRating:
          $ref: '#/components/schemas/RetailerRating'
        retailerReview:
          $ref: '#/components/schemas/RetailerReview'
        isTopRetailer:
          type: boolean
          description: Retailer flag if top seller or not.
          example: true
          nullable: true
    RetailerRating:
      type: object
      description: Represents rating on retailer, product, delivery time, shipping and service level.
      required:
        - retailerRating
      properties:
        retailerRating:
          description: Retailer general rating.
          example: 9
          type: number
          minimum: 1
          maximum: 10
        productInformationRating:
          description: Retailer product rating.
          example: 9
          type: number
          minimum: 1
          maximum: 10
          nullable: true
        deliveryTimeRating:
          description: Retailer delivery time rating.
          example: 9
          type: number
          minimum: 1
          maximum: 10
          nullable: true
        shippingRating:
          description: Retailer shipping rating.
          example: 9
          type: number
          minimum: 1
          maximum: 10
          nullable: true
        serviceRating:
          description: Retailer service rating.
          example: 9
          type: number
          minimum: 1
          maximum: 10
          nullable: true
    RetailerReview:
      type: object
      description: Represents positive, negative, neutral and total review count.
      required:
        - totalReviewCount
        - positiveReviewCount
        - neutralReviewCount
        - negativeReviewCount
      properties:
        totalReviewCount:
          description: The total amount of customer review during the rating method period.
          example: 10
          type: integer
          format: int32
          minimum: 0
        approvalPercentage:
          description: >-
            The percentage of customers that
            rated the retailer either neutral or positive during the rating
            method period.
          example: 80
          type: number
          minimum: 0
          maximum: 100
        positiveReviewCount:
          description: >-
            The amount of positive customer reviews during the rating method
            period.
          example: 70
          type: integer
          format: int32
          minimum: 0
        neutralReviewCount:
          description: >-
            The amount of neutral customer reviews during the rating method
            period.
          example: 10
          type: integer
          format: int32
          minimum: 0
        negativeReviewCount:
          description: >-
            The amount of negative customer reviews during the rating method
            period.
          example: 10
          type: integer
          format: int32
          minimum: 0
    RatingMethod:
      type: string
      description: >-
        An identifier that identifies if the rating is calculated over the past
        three months or on all reviews for the retailer.
      example: ALL_REVIEWS
      enum:
        - ALL_REVIEWS
        - RECENT_REVIEWS
    RetailerInformation:
      description: Represents general retailer's shop related information.
      required:
        - retailerId
        - displayName
        - registrationDateTime
        - companyName
        - vatNumber
        - countryAvailability
      properties:
        retailerId:
          $ref: "../common/models.yaml#/components/schemas/retailerId"
        displayName:
          type: string
          description: The shop name of the retailer.
          example: The shop name
        companyName:
          $ref: "../common/models.yaml#/components/schemas/companyName"
        vatNumber:
          $ref: "../common/models.yaml#/components/schemas/vatNumber"
        kvkNumber:
          $ref: "../common/models.yaml#/components/schemas/kvkNumber"
        registrationDateTime:
          allOf:
            - description: "A date and time (ISO 8601), representing the registration date and time
            for the retailer within bol."
          $ref: "../common/models.yaml#/components/schemas/dateTime"
        countryAvailability:
          type: array
          items:
            $ref: "../common/models.yaml#/components/schemas/countryCode"
    PerformanceStatus:
      type: object
      description: Represents the retailer's current operational and behavioral performance in the bol platform.
      properties:
        monitoringSystem:
          $ref: '#/components/schemas/MonitoringSystem'
        policy:
          $ref: '#/components/schemas/Policy'
    MonitoringSystem:
      type: object
      description: Represents retailer's current monitoring system name and strike information.
      required:
        - description
      properties:
        description:
          type: string
          description: Name of the current monitoring system the retailer is in.
          example: GroeiStart
        strike:
          $ref: '#/components/schemas/Strike'
    Strike:
      type: object
      description: Represents retailer's strike information.
      required:
        - count
        - weeks
        - monitorPeriod
      properties:
        count:
          description: The number of strikes in the current monitoring weeks.
          example: 0
          type: integer
          format: int32
          minimum: 0
          maximum: 7
        weeks:
          type: array
          items:
            $ref: '#/components/schemas/StrikeWeekReason'
        monitorPeriod:
          $ref: '#/components/schemas/MonitorPeriod'
    StrikeWeekReason:
      type: object
      description: Represents the week and KPI(s) for which the retailer under performed.
      required:
        - week
        - reasons
      properties:
        week:
          type: string
          description: Strike week in the format YYYY-WW (ISO-8601).
          example: 2025-01
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/StrikeReason'
    StrikeReason:
      type: string
      description: Name(s) of the underperformed KPI.
      example: FULFILMENT
      enum:
        - CANCELLATIONS
        - FULFILMENT
        - HANDOVER
        - ON_TIME
        - RESPONSE_TIME
    MonitorPeriod:
      type: object
      description: Represents start and end week of the monitoring period. Currently 22 weeks.
      required:
        - startWeek
        - endWeek
      properties:
        startWeek:
          type: string
          description: The start week of the monitor period in the format YYYY-WW (ISO-8601).
          example: 2025-01
        endWeek:
          type: string
          description: The end week of the monitor period in the format YYYY-WW (ISO-8601).
          example: 2025-22
    Policy:
      type: object
      description: Represents policy violation overview.
      required:
        - pointsLeft
      properties:
        pointsLeft:
          description: Remaining policy violation points(0-100).
          example: 90
          minimum: 0
          maximum: 100
          type: integer
          format: int32
        violations:
          type: array
          items:
            $ref: '#/components/schemas/PolicyViolation'
    PolicyViolation:
      type: object
      description: Represents details of all the policy violations and second chance registered in the last 365 days from the current day.
      required:
        - violationId
        - registrationDateTime
        - category
        - subCategory
        - violationType
        - points
        - isProportionalityApplied
      properties:
        violationId:
          type: string
          description: The unique identifier of a policy violation.
          example: blue-210328350
        registrationDateTime:
          allOf:
            - description: "The date time when the policy violation was registered in ISO-8601 format."
          $ref: "../common/models.yaml#/components/schemas/dateTime"
        category:
          type: string
          description: Policy violated category name.
          example: FORBIDDEN_ASSORTMENT
          enum:
            - SELF_PROMOTION
            - PRODUCT_INFORMATION
            - UNWANTED_COMMUNICATION
            - BRAND
            - PERFORMANCE
            - UNWANTED_ASSORTMENT
            - FORBIDDEN_ASSORTMENT
            - IMITATION
            - FRAUD
            - SECOND_CHANCE
            - OTHER
        subCategory:
          type: string
          description: Policy violated sub-category name.
          example: MISSING_QUALITY_MARK
          enum:
            - REFERENCE_OWN_COMPANY_DATA
            - COMMERCIAL_ACTION
            - DOUBLE_OFFER
            - FAKE_REVIEWS
            - ORGANIC_RANK_MANIPULATION
            - DIFFERENT_ARTICLE
            - WRONG_CONTENT
            - MISLEADING_CLAIMS
            - UNSUITABLE_FOR_SALE
            - DECLARED_UNDESIRABLE
            - BELOW_STANDARD
            - DANGEROUS_FOR_CUSTOMER
            - BYPASS_BLOCKAGE
            - TRADEMARK_INFRINGEMENT
            - PATENT_INFRINGEMENT
            - COPYRIGHT_INFRINGEMENT
            - BYPASS_TRADEMARK_AUTHORIZATION
            - BYPASS_STRIKE_PROCESS
            - BYPASS_KPI_CANCELLATIONS
            - BYPASS_KPI_FULFILMENT
            - BYPASS_KPI_RESPONSE_TIME
            - BYPASS_KPI_REVIEWS
            - INAPPROPRIATE_LANGUAGE
            - BLACKMAIL
            - SPAM
            - INCORRECT_CONTACT_INFORMATION
            - LEGALLY_PROHIBITED_ARTICLE
            - DISOBEY_LEGAL_REQUIREMENTS
            - MISSING_QUALITY_MARK
            - IMMITATION
            - DECODED_PRODUCT
            - INCORRECT_COMPANY_DATA
            - PREVIOUSLY_CLOSED_PARTNER
            - PAYMENT_REQUEST
            - DELIVERY
            - RETURNS
            - SERVICE
            - INVOICES
            - FULFILMENT
            - PRIVACY
            - NO_COMPLIANCE
            - OTHER
            - DELIVERY_OUTSIDE_eu
            - BYPASS_ntd_PROCESS
            - UNJUSTIFIED_COMPLAINTS
            - NOT_APPLICABLE
        violationType:
          type: string
          description: Type of the policy violation.
          example: POINTS_DEDUCTION
          enum:
            - POINTS_ADDITION
            - POINTS_DEDUCTION
            - WARNING
        points:
          type: integer
          description: The number of points assigned to the policy violation.
          example: 10
          minimum: 0
          maximum: 100
          format: int32
        isProportionalityApplied:
          type: boolean
          description: Has the number of points deducted been lowered because of proportionality to offer and order count.
        preProportionalPoints:
          type: integer
          description: The number of points that would have been deducted without proportionality correction, as indicated by isProportionalityApplied.
          example: 20
          minimum: 0
          maximum: 100
          format: int32
    KpiScore:
      type: object
      description: Represents the KPI's score, norm and whether the KPI is excluded from strike calculation or not.
      required:
        - kpi
        - norm
        - period
        - excluded
      properties:
        kpi:
          type: string
          description: Name of the service norm.
          example: FULFILMENT
          enum:
            - CANCELLATIONS
            - CASE_ITEM_RATIO
            - FULFILMENT
            - HANDOVER
            - ON_TIME
            - RESPONSE_TIME
            - RETURNS
            - REVIEWS
            - TRACK_AND_TRACE
        score:
          $ref: '#/components/schemas/Score'
        norm:
          $ref: '#/components/schemas/Norm'
        period:
          $ref: '#/components/schemas/Period'
        excluded:
          type: boolean
          description: Flag to represent whether the KPI is excluded from strike calculation or not.
          example: false
    Norm:
      type: object
      description: Represents the norm of the KPI.
      required:
        - condition
        - type
        - value
      properties:
        type:
          type: string
          description: Norm type used for the service norm.
          example: FIXED
          enum:
            - DYNAMIC
            - FIXED
        condition:
          type: string
          description: Logical operator used for the norm and score.
          example: lte
        value:
          type: number
          description: Actual norm used for the service norm.
          example: 0.02
          format: float
    Period:
      type: object
      description: Period for which the score was calculated.
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: Week in the format YYYY-WW (ISO-8601).
          example: 2025-01
        type:
          type: string
          description: Period type for the score. Currently can only be "week".
          example: WEEK
          enum:
            - WEEK
    Score:
      type: object
      description: The score of the service norm.
      required:
        - denominator
        - numerator
        - value
        - distanceToNorm
        - conformsToNorm
      properties:
        numerator:
          type: integer
          description: The numerator of the score.
          example: 2
          format: int32
        denominator:
          type: integer
          description: The denominator of the score.
          example: 2
          format: int32
        value:
          type: number
          description: The value of the score.
          example: 1.0
          format: float
        distanceToNorm:
          type: number
          description: Value representing distance between score and the norm.
          example: 0.02
          format: float
        conformsToNorm:
          type: boolean
          description: A flag which says whether score conforms to the norm or not.
          example: true
  responses:
    "200_GET_KPI_SCORE_SUCCESSFUL":
      description: "The request was successful, and the kpi score have been retrieved successfully."
      content:
        application/vnd.retailer.v11+json:
          schema:
            $ref: "#/components/schemas/KpiScore"
    "200_GET_PERFORMANCE_STATUS_SUCCESSFUL":
      description: "The request was successful, and the performance status has been retrieved successfully."
      content:
        application/vnd.retailer.v11+json:
          schema:
            $ref: "#/components/schemas/PerformanceStatus"
    "200_GET_RETAILER_RATINGS_SUCCESSFUL":
      description: "The request was successful, and the retailer ratings have been retrieved successfully."
      content:
        application/vnd.retailer.v11+json:
          schema:
            $ref: "#/components/schemas/RetailerRatings"
    "200_GET_RETAILER_INFO_SUCCESSFUL":
      description: "The request was successful, and the retailer information has been retrieved successfully."
      content:
        application/vnd.retailer.v11+json:
          schema:
            $ref: "#/components/schemas/RetailerInformation"
