Bol Insights API

openapi: 3.2.0
info:
  title: v10 - Retailer Insights 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: Insights
  description: Insights resource
paths:
  /retailer/insights/offer:
    get:
      tags:
      - Insights
      summary: Get offer insights
      description: Get the product visits and the buy box percentage for an offer during a given period.
      operationId: get-offer-insights
      parameters:
      - name: offer-id
        in: query
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      - name: period
        in: query
        description: The time unit in which the offer insights are grouped.
        required: true
        schema:
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
      - name: number-of-periods
        in: query
        description: The number of periods for which the offer insights are requested back in time. The maximum available periods are 24 for MONTH, 104 for WEEK, and 730 for DAY.
        required: true
        schema:
          type: integer
          format: int32
      - name: name
        in: query
        description: The name of the requested offer insight.
        required: true
        schema:
          type: string
          enum:
          - PRODUCT_VISITS
          - BUY_BOX_PERCENTAGE
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/OfferInsights'
        '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'
  /retailer/insights/performance/indicator:
    get:
      tags:
      - Insights
      summary: Get performance indicators
      description: Gets the measurements for your performance indicators per week.
      operationId: get-performance-indicators
      parameters:
      - name: name
        in: query
        description: The type of the performance indicator
        required: true
        schema:
          type: string
          enum:
          - CANCELLATIONS
          - FULFILMENT
          - PHONE_AVAILABILITY
          - RESPONSE_TIME
          - CASE_ITEM_RATIO
          - TRACK_AND_TRACE
          - RETURNS
          - REVIEWS
      - name: year
        in: query
        description: Year number in the ISO-8601 standard.
        required: true
        schema:
          type: string
      - name: week
        in: query
        description: Week number in the ISO-8601 standard. If you would like to get the relative scores from the current week, please provide the current week number here. Be advised that measurements can change heavily over the course of the week.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/PerformanceIndicators'
        '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'
  /retailer/insights/product-ranks:
    get:
      tags:
      - Insights
      summary: Get product ranks
      description: Gets a list of product ranks.
      operationId: get-product-ranks
      parameters:
      - name: ean
        in: query
        description: The EAN number associated with this product.
        required: true
        schema:
          type: string
      - name: date
        in: query
        description: Filters search results to a specific date. The date must be in the past, no more than three months back, and up to yesterday.
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Determines the search type, either 'SEARCH' for specific queries or 'BROWSE' for broader category searches. In order to retrieve all results, it can be sent as "null".
        required: false
        schema:
          type: string
          enum:
          - SEARCH
          - BROWSE
      - name: page
        in: query
        description: The requested page number with a page size of 50 items.
        required: false
        schema:
          maximum: 200
          minimum: 1
          type: integer
          format: int32
          default: 1
        example: 1
      - name: Accept-Language
        in: header
        description: The language to search for.
        required: false
        schema:
          type: string
          enum:
          - nl-NL
          - nl
          - nl-BE
          - fr
          - fr-BE
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ProductRanks'
        '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'
        '406':
          description: 'Not acceptable: The sent request header 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'
  /retailer/insights/sales-forecast:
    get:
      tags:
      - Insights
      summary: Get sales forecast
      description: Get sales forecast to estimate the sales expectations on the total bol.com platform for the requested number of weeks ahead.
      operationId: get-sales-forecast
      parameters:
      - name: offer-id
        in: query
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      - name: weeks-ahead
        in: query
        description: The number of weeks into the future, starting from today.
        required: true
        schema:
          maximum: 12
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/SalesForecastResponse'
        '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'
  /retailer/insights/search-terms:
    get:
      tags:
      - Insights
      summary: Get search terms
      description: Retrieves the search volume for a specified search term and period. The search volume allows you to see what bol.com customers are searching for. Based on the search volume per search term you can optimize your product content, or spot opportunities to extend your assortment, or analyzing trends for inventory management.
      operationId: get-search-terms
      parameters:
      - name: search-term
        in: query
        description: The search term for which you want to request the search volume.
        required: true
        schema:
          type: string
      - name: period
        in: query
        description: The time unit in which the offer insights are grouped.
        required: true
        schema:
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
      - name: number-of-periods
        in: query
        description: The number of periods for which the offer insights are requested back in time.
        required: true
        schema:
          type: integer
          format: int32
      - name: related-search-terms
        in: query
        description: Indicates whether or not you want to retrieve the related search terms.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/SearchTerms'
        '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'
components:
  schemas:
    TotalPeriod:
      required:
      - countries
      - period
      - total
      type: object
      properties:
        period:
          $ref: '#/components/schemas/SearchTermsPeriod'
        total:
          type: integer
          description: The number of customer visits on the search page.
          format: int32
          example: 100
        countries:
          type: array
          items:
            $ref: '#/components/schemas/SearchTermsCountry'
    ProductRanks:
      required:
      - hasNextPage
      - ranks
      type: object
      properties:
        ranks:
          type: array
          description: The list of ranks associated with the product.
          items:
            $ref: '#/components/schemas/Rank'
        hasNextPage:
          type: boolean
          description: Indicator if there is a next page of ranks (true/false).
          example: false
    PerformanceIndicatorPeriod:
      required:
      - week
      - year
      type: object
      properties:
        week:
          type: string
          description: Week number in the ISO-8601 standard.
          example: '05'
        year:
          type: string
          description: Year number in the ISO-8601 standard.
          example: '2019'
      description: The period for which the performance is measured.
    Total:
      required:
      - maximum
      - minimum
      type: object
      properties:
        minimum:
          type: number
          description: Minimum number of estimated sales expectations on the bol.com platform.
          format: double
          example: 10.5
        maximum:
          type:
          - number
          - 'null'
          description: Maximum number of estimated sales expectations on the bol.com platform.
          format: double
          example: 20.5
    OfferInsightsCountry:
      required:
      - countryCode
      - value
      type: object
      properties:
        countryCode:
          type: string
          description: Countries in which this offer is currently on sale in the webshop, in ISO-3166-1 format.
          example: NL
        value:
          type: number
          description: The total value of offer insight.
          format: double
          example: 100.0
    OfferInsightsPeriod:
      required:
      - year
      type: object
      properties:
        day:
          type:
          - integer
          - 'null'
          description: Day of the month.
          format: int32
          example: 1
        week:
          type:
          - integer
          - 'null'
          description: Week of the year.
          format: int32
          example: 49
        month:
          type:
          - integer
          - 'null'
          description: Month of the year.
          format: int32
          example: 12
        year:
          type: integer
          description: Year.
          format: int32
          example: 2019
    Periods:
      required:
      - period
      type: object
      properties:
        period:
          $ref: '#/components/schemas/OfferInsightsPeriod'
        total:
          type:
          - number
          - 'null'
          description: Total number of customer visits on the product page when the offer had the buy box over the requested period (excluding the current day).
          format: double
          example: 50
        countries:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OfferInsightsCountry'
    Score:
      required:
      - conforms
      - denominator
      - distanceToNorm
      - numerator
      - value
      type: object
      properties:
        conforms:
          type: boolean
          description: Indicates whether the score conforms to the bol.com service norm or not.
          example: true
        numerator:
          type: integer
          description: The top part of the fraction (above the line). This usually is the smaller number compared to the denominator.
          format: int32
          example: 5
        denominator:
          type: integer
          description: The lower part of the fraction (below the line). This usually is the larger number compared to the the numerator.
          format: int32
          example: 10
        value:
          type: number
          description: The score for this measurement (denominator divided by the numerator).
          format: float
          example: 0.5
        distanceToNorm:
          type: number
          description: The difference between the score and the bol.com service norm.
          format: float
          example: 0.1
      description: The score for this measurement. In case there are no scores for an indicator, this element is omitted from the response.
    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.
    SalesForecastPeriod:
      required:
      - countries
      - total
      - weeksAhead
      type: object
      properties:
        weeksAhead:
          type: integer
          description: The number of weeks into the future, starting from today.
          format: int32
          example: 2
        total:
          $ref: '#/components/schemas/Total'
        countries:
          type: array
          items:
            $ref: '#/components/schemas/Countries'
    OfferInsights:
      required:
      - offerInsights
      type: object
      properties:
        offerInsights:
          type: array
          items:
            $ref: '#/components/schemas/OfferInsight'
      description: Offer insights.
    SearchTermsPeriod:
      type: object
      properties:
        day:
          type:
          - string
          - 'null'
          description: Day number in the ISO-8601 standard.
          example: '19'
        week:
          type:
          - string
          - 'null'
          description: Week number in the ISO-8601 standard.
          example: '41'
        month:
          type:
          - string
          - 'null'
          description: Month number in the ISO-8601 standard.
          example: '11'
        year:
          type:
          - string
          - 'null'
          description: Year number in the ISO-8601 standard.
          example: '2020'
    PerformanceIndicators:
      required:
      - performanceIndicators
      type: object
      properties:
        performanceIndicators:
          type: array
          items:
            $ref: '#/components/schemas/PerformanceIndicator'
    Norm:
      required:
      - condition
      - value
      type: object
      properties:
        condition:
          type: string
          description: Condition norm for this indicator.
          example: <=
          enum:
          - <=
          - '>='
        value:
          type: number
          description: Service norm for this indicator.
          format: float
          example: 0.6
      description: Service norm for this indicator.
    SalesForecastResponse:
      required:
      - countries
      - name
      - periods
      - total
      - type
      type: object
      properties:
        name:
          type: string
          description: Indicator name.
          example: SALES_FORECAST
        type:
          type: string
          description: Interpretation of the data that applies to this measurement.
          example: DECIMAL
        total:
          $ref: '#/components/schemas/Total'
        countries:
          type: array
          items:
            $ref: '#/components/schemas/Countries'
        periods:
          type: array
          items:
            $ref: '#/components/schemas/SalesForecastPeriod'
    OfferInsight:
      required:
      - countries
      - name
      - periods
      - type
      type: object
      properties:
        name:
          type: string
          description: The name of the requested offer insight.
          example: BUY_BOX_PERCENTAGE
        type:
          type: string
          description: Interpretation of the data that applies to this measurement.
          example: percentage
        total:
          type:
          - number
          - 'null'
          description: Total number of customer visits on the product page when the offer had the buy box over the requested period (excluding the current day).
          format: double
          example: 50
        countries:
          type: array
          items:
            $ref: '#/components/schemas/OfferInsightsCountry'
        periods:
          type: array
          items:
            $ref: '#/components/schemas/Periods'
    RelatedSearchTerm:
      required:
      - searchTerm
      - total
      type: object
      properties:
        total:
          type: integer
          description: The number of customer visits on the search page.
          format: int32
          example: 100
        searchTerm:
          type: string
          description: The search term for which you requested the search volume.
          example: book
    SearchTermsCountry:
      required:
      - countryCode
      - value
      type: object
      properties:
        countryCode:
          type: string
          description: Countries in which this offer is currently on sale in the webshop in ISO-3166-1 format.
          example: NL
        value:
          type: integer
          description: The number of customer visits on the search page.
          format: int32
          example: 100
    Details:
      required:
      - norm
      - period
      type: object
      properties:
        period:
          $ref: '#/components/schemas/PerformanceIndicatorPeriod'
        score:
          allOf:
          - $ref: '#/components/schemas/Score'
        norm:
          $ref: '#/components/schemas/Norm'
      description: Details of the indicator.
    SearchTerm:
      required:
      - countries
      - periods
      - searchTerm
      - total
      - type
      type: object
      properties:
        searchTerm:
          type: string
          description: The search term for which you requested the search volume.
          example: book
        type:
          type: string
          description: Interpretation of the data that applies to this measurement.
          example: count
        total:
          type: integer
          description: The number of customer visits on the search page.
          format: int32
          example: 100
        countries:
          type: array
          items:
            $ref: '#/components/schemas/SearchTermsCountry'
        periods:
          type: array
          items:
            $ref: '#/components/schemas/TotalPeriod'
        relatedSearchTerms:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/RelatedSearchTerm'
    Rank:
      required:
      - impressions
      - rank
      - wasSponsored
      type: object
      properties:
        categoryId:
          type:
          - string
          - 'null'
          description: The ID of the category to which the product belongs.
          example: '53495'
        searchTerm:
          type:
          - string
          - 'null'
          description: Search term related to the rank.
          example: dvd
        wasSponsored:
          type: boolean
          description: Indicator if the product is sponsored or not.
          example: false
        rank:
          type: integer
          description: The rank of the product in the category or search page.
          format: int32
          example: 1
        impressions:
          type: integer
          description: Number of viewable impressions of the product.
          format: int32
          example: 100
      description: The list of ranks associated with the product.
    SearchTerms:
      type: object
      properties:
        searchTerms:
          allOf:
          - $ref: '#/components/schemas/SearchTerm'
    Countries:
      required:
      - maximum
      - minimum
      type: object
      properties:
        countryCode:
          type:
          - string
          - 'null'
          description: Countries in which this offer is currently on sale in the webshop, in ISO-3166-1 format.
          example: NL
        minimum:
          type: number
          description: Minimum number of estimated sales expectations on the bol.com platform.
          format: double
          example: 10.5
        maximum:
          type:
          - number
          - 'null'
          description: Maximum number of estimated sales expectations on the bol.com platform.
          format: double
          example: 20.5
    PerformanceIndicator:
      required:
      - details
      - name
      - type
      type: object
      properties:
        name:
          type: string
          description: Indicator name.
          example: CANCELLATIONS
          enum:
          - CANCELLATIONS
          - FULFILMENT
          - PHONE_AVAILABILITY
          - RESPONSE_TIME
          - CASE_ITEM_RATIO
          - TRACK_AND_TRACE
          - RETURNS
          - REVIEWS
        type:
          type: string
          description: Interpretation of the data that applies to this measurement.
          example: PERCENTAGE
          enum:
          - PERCENTAGE
          - AVERAGE
        details:
          $ref: '#/components/schemas/Details'
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer