Bol Retailers API

openapi: 3.2.0
info:
  title: v10 - Retailer Retailers API
  description: 'The bol.com API for retailers.


    # Authentication

    Our API requires authentication via OAuth2. The detailed steps to authenticate are explained here


    # Demo scenarios

    Our API specification includes examples of the responses you can expect. For more information as well as more examples, we refer you to the following resources:

    - Demo environment

    - Demo scenarios'
  termsOfService: https://api.bol.com/retailer/public/Retailer-API/legal/terms-of-service.html
  contact:
    name: developers.bol.com
    url: https://developers.bol.com
  version: 10.x
  x-logo:
    url: https://api.bol.com/retailer/public/Retailer-API/_images/bolcom_logo.png
    altText: bol.com logo
security:
- OAuth2: []
tags:
- name: Retailers
  description: Retailers resource
paths:
  /retailer/retailers/{retailer-id}:
    get:
      tags:
      - Retailers
      summary: Get retailer information by retailer id
      description: Gets retailer information of a single retailer.
      operationId: get-retailer-information
      parameters:
      - name: retailer-id
        in: path
        description: The Id of the retailer which information belongs to. Use 'current' to retrieve information about your own retailer account.
        required: true
        schema:
          type: string
        example: 1055479
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/RetailerInformationResponse'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    RetailerRating:
      required:
      - retailerRating
      type: object
      properties:
        retailerRating:
          maximum: 10
          minimum: 1
          type: number
          description: General rating of the retailer.
          format: double
          example: 9.1
        productInformationRating:
          maximum: 10
          minimum: 1
          type:
          - number
          - 'null'
          description: Product rating of the retailer.
          format: double
          example: 9.6
        deliveryTimeRating:
          maximum: 10
          minimum: 1
          type:
          - number
          - 'null'
          description: Delivery rating of the retailer.
          format: double
          example: 9.4
        shippingRating:
          maximum: 10
          minimum: 1
          type:
          - number
          - 'null'
          description: Shipping rating of the retailer.
          format: double
          example: 9.4
        serviceRating:
          maximum: 10
          minimum: 1
          type:
          - number
          - 'null'
          description: Service rating of the retailer.
          format: double
          example: 9.4
      description: Rating on different aspects all being one decimal precision.
    RetailerInformationResponse:
      required:
      - companyName
      - displayName
      - kvkNumber
      - registrationDate
      - retailerId
      - vatNumber
      type: object
      properties:
        retailerId:
          type: string
          description: The Id of the retailer which information belongs to.
          example: '1055479'
        displayName:
          type: string
          description: The name of the retailer visible on bol.com
          example: RETAILER123
        companyName:
          type: string
          description: The company name of the retailer.
          example: Fietsentuin
        vatNumber:
          type: string
          description: The VAT number of the retailer.
          example: NL123456789B01
        kvkNumber:
          type:
          - string
          - 'null'
          description: The KVK number of the retailer.
          example: '90005414'
        registrationDate:
          type: string
          description: A date representing the registration date for the retailer within bol.com
          example: '2015-06-17'
        topRetailer:
          type:
          - boolean
          - 'null'
          description: Indication of retailer's being the top seller.
          example: false
        ratingMethod:
          type:
          - string
          - 'null'
          description: An identifier that identifies if the rating is calculated over the past three months or on all reviews for the retailer.
          example: THREE_MONTHS
          enum:
          - ALL_REVIEWS
          - THREE_MONTHS
          - null
        retailerRating:
          allOf:
          - $ref: '#/components/schemas/RetailerRating'
        retailerReview:
          allOf:
          - $ref: '#/components/schemas/RetailerReview'
    Problem:
      required:
      - detail
      - status
      - title
      - type
      - violations
      type: object
      properties:
        type:
          type: string
          description: 'Type URI for this problem. Fixed value: https://api.bol.com/problems.'
          format: uri
          example: https://api.bol.com/problems
        title:
          type: string
          description: Title describing the nature of the problem.
          example: Error validating request. Consult the bol.com API documentation for more information.
        status:
          type: integer
          description: HTTP status returned from the endpoint causing the problem.
          format: int32
        detail:
          type: string
          description: Detailed error message describing in additional detail what caused the service to return this problem.
          example: Bad request
        host:
          type:
          - string
          - 'null'
          description: Host identifier describing the server instance that reported the problem.
          example: Instance-001
        instance:
          type:
          - string
          - 'null'
          description: Full URI path of the resource that reported the problem.
          format: uri
          example: https://api.bol.com//retailer/resource
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
      description: Describes a problem that occurred interacting with the API.
    Violation:
      required:
      - name
      - reason
      type: object
      properties:
        name:
          type: string
          description: Describes the origin of the error, for instance a field or query parameter validation error.
          example: exampleValue
        reason:
          type: string
          description: Detailed description of the validation error that caused the problem.
          example: 'Request contains invalid value(s): ''INVALID'', allowed values: ALLOWED_VALUE1, ALLOWED_VALUE2.'
      description: Describes a violation that occurred interacting with the API.
    RetailerReview:
      required:
      - negativeReviewCount
      - neutralReviewCount
      - positiveReviewCount
      - totalReviewCount
      type: object
      properties:
        totalReviewCount:
          minimum: 0
          type: integer
          description: The total amount of customer review during that rating method period.
          format: int32
          example: 14
        approvalPercentage:
          maximum: 10
          minimum: 0
          type:
          - integer
          - 'null'
          description: The percentage of the amount of customer that rated the retailer either neutral or positive during the rating method period.
          format: int32
          example: 100
        positiveReviewCount:
          minimum: 0
          type: integer
          description: The amount of positive customer reviews during that rating method period.
          format: int32
          example: 13
        neutralReviewCount:
          minimum: 0
          type: integer
          description: The amount of neutral customer reviews during that rating method period.
          format: int32
          example: 1
        negativeReviewCount:
          minimum: 0
          type: integer
          description: The amount of negative customer reviews during that rating method period.
          format: int32
          example: 0
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer