Bol Commissions API

openapi: 3.2.0
info:
  title: v10 - Retailer Commissions 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: Commissions
  description: Commissions resource
paths:
  /retailer/commission:
    post:
      tags:
      - Commissions
      summary: Get all commissions and reductions by EAN in bulk
      description: Gets all commissions and possible reductions by EAN, price, and optionally condition.
      operationId: get-commissions
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/BulkCommissionRequest'
        required: true
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/BulkCommissionResponse'
        '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'
  /retailer/commission/{ean}:
    get:
      tags:
      - Commissions
      summary: Get all commissions and reductions by EAN per single EAN
      description: Commissions can be filtered by condition, which defaults to NEW. We will calculate the commission amount from the EAN and price.
      operationId: get-commission
      parameters:
      - name: ean
        in: path
        description: The EAN number associated with this product.
        required: true
        schema:
          type: string
        example: '0000007740404'
      - name: condition
        in: query
        description: The condition of the offer.
        required: false
        schema:
          type: string
          enum:
          - NEW
          - AS_NEW
          - GOOD
          - REASONABLE
          - MODERATE
      - name: unit-price
        in: query
        description: The price of the product with a period as a decimal separator. The price should always have two decimals precision.
        required: true
        schema:
          maximum: 9999
          minimum: 0
          type: number
        example: 59.0
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Commission'
        '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'
  /retailer/commissions:
    post:
      tags:
      - Commissions
      summary: Get a list of commissions by EAN (BETA)
      description: Gets a list of all commissions using EAN.
      operationId: get-commission-rates
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/CommissionProducts'
        required: true
      responses:
        '207':
          description: 'Multi-status: Retrieved successful and unsuccessful results.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/BulkCommissionRatesMultiStatusResponse'
        '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:
    BulkCommissionRatesMultiStatusResponse:
      required:
      - failedQueries
      - successfulQueries
      type: object
      properties:
        successfulQueries:
          type: array
          items:
            $ref: '#/components/schemas/CommissionSuccessfulQuery'
        failedQueries:
          type: array
          items:
            $ref: '#/components/schemas/CommissionFailedQuery'
    Ean:
      required:
      - ean
      type: object
      properties:
        ean:
          type: string
          description: The EAN number associated with this product.
          example: '0000007740404'
    CommissionProducts:
      required:
      - products
      type: object
      properties:
        products:
          maxItems: 100
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/Ean'
    CommissionDateRate:
      required:
      - condition
      - priceRanges
      type: object
      properties:
        condition:
          type: string
          description: Condition of the product.
          example: NEW
        priceRanges:
          type: array
          items:
            $ref: '#/components/schemas/CommissionPriceRange'
      description: An array of objects, each describing commission rates for a specific condition.
    Commission:
      required:
      - condition
      - ean
      - fixedAmount
      - percentage
      - reductions
      - totalCost
      - unitPrice
      type: object
      properties:
        ean:
          type:
          - string
          - 'null'
          description: The EAN number associated with this product.
          example: '0000007740404'
        condition:
          type:
          - string
          - 'null'
          description: The condition of the offer.
          example: NEW
        unitPrice:
          type: number
          description: The intended selling price per single unit up to 2 decimals precision, including VAT.
          example: 59.0
        fixedAmount:
          type: number
          description: A fixed commission fee, including VAT.
          example: 0.99
        percentage:
          type: number
          description: A percentage of commission, based on the intended selling price per unit, including VAT.
          example: 15
        totalCost:
          type: number
          description: The total commission for selling this product at bol.com. The price includes VAT for Dutch sellers, and excludes VAT for Belgium sellers.
          example: 6.85
        totalCostWithoutReduction:
          type:
          - number
          - 'null'
          description: The total commission for selling this product at bol.com without reductions including VAT.
          example: 9.84
        reductions:
          type: array
          items:
            $ref: '#/components/schemas/Reduction'
    BulkCommissionQuery:
      required:
      - ean
      - unitPrice
      type: object
      properties:
        ean:
          minLength: 1
          type: string
          description: The EAN number associated with this product.
          example: '0000007740404'
        condition:
          type:
          - string
          - 'null'
          description: The condition of the offer.
          example: NEW
          enum:
          - NEW
          - AS_NEW
          - GOOD
          - REASONABLE
          - MODERATE
          - null
        unitPrice:
          maximum: 9999
          minimum: 0
          type: number
          description: The price of the product with a period as a decimal separator. The price should always have two decimals precision.
          example: 59.0
    CommissionFailedQuery:
      required:
      - index
      - status
      - violations
      type: object
      properties:
        index:
          type: number
          description: This provides the location of the entity where it was provided in the original response body.
          example: 1
        status:
          type: integer
          description: HTTP status code for individual entity operation.
          format: int32
          example: 400
        violations:
          type: array
          description: Outlines the list of violations encountered in the API for the specific index detailing the nature and reason for the issue.
          items:
            $ref: '#/components/schemas/Violation'
    CommissionDateRange:
      required:
      - endDate
      - rates
      - startDate
      type: object
      properties:
        startDate:
          type: string
          description: The inclusive start date (in ISO 8601 format) from which the commission applies
          example: '1970-01-01'
        endDate:
          type: string
          description: The exclusive end date (in ISO 8601 format) after which the commission no longer applies.
          example: '1970-01-01'
        rates:
          type: array
          description: An array of objects, each describing commission rates for a specific condition.
          items:
            $ref: '#/components/schemas/CommissionDateRate'
      description: An array of objects, each describing a period during which certain commission rates apply.
    Reduction:
      required:
      - costReduction
      - endDate
      - maximumPrice
      - startDate
      type: object
      properties:
        maximumPrice:
          type: number
          description: Maximum offer price that can be used to benefit from a commission reduction, including VAT.
          example: 60.0
        costReduction:
          type: number
          description: A reduction to the commission if the maximum price criteria is met, including VAT.
          example: 2.99
        startDate:
          type: string
          description: The start date from which the commission reduction is valid, in ISO 8601 format.
          format: date
          example: '2018-01-01'
        endDate:
          type: string
          description: The end date from which the commission reduction is not valid anymore, in ISO 8601 format.
          format: date
          example: '2018-01-30'
    CommissionRate:
      required:
      - dateRanges
      - ean
      type: object
      properties:
        ean:
          type: string
          description: The EAN number associated with this product.
          example: '0000007740404'
        dateRanges:
          type: array
          description: An array of objects, each describing a period during which certain commission rates apply.
          items:
            $ref: '#/components/schemas/CommissionDateRange'
    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.
    BulkCommissionResponse:
      required:
      - commissions
      type: object
      properties:
        commissions:
          type: array
          items:
            $ref: '#/components/schemas/Commission'
    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.
    CommissionPriceRange:
      required:
      - fixedAmount
      - percentage
      - range
      - reductionApplied
      type: object
      properties:
        range:
          $ref: '#/components/schemas/CommissionRange'
        fixedAmount:
          type: number
          description: The fixed commission amount excluding VAT.
          example: 0
        percentage:
          type: number
          description: A percentage of commission, based on the intended selling price per unit, excluding VAT.
          example: 20
        reductionApplied:
          type: boolean
          description: A boolean flag indicating whether a reduction is applied to the commission or not.
          example: true
    CommissionRange:
      required:
      - lower
      type: object
      properties:
        lower:
          type: number
          description: The inclusive lower price threshold for which the commission is valid.
          example: 0
        upper:
          type:
          - number
          - 'null'
          description: The exclusive upper price threshold for which the commission is valid.
          example: 10
      description: Defines a specific price range for which the commission rates apply including VAT.
    CommissionSuccessfulQuery:
      required:
      - commissionRates
      - index
      - status
      type: object
      properties:
        index:
          type: number
          description: This provides the location of the entity where it was provided in the original response body.
          example: 0
        status:
          type: integer
          description: HTTP status code for individual entity operation.
          format: int32
          example: 200
        commissionRates:
          type: array
          items:
            $ref: '#/components/schemas/CommissionRate'
    BulkCommissionRequest:
      required:
      - commissionQueries
      type: object
      properties:
        commissionQueries:
          maxItems: 100
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/BulkCommissionQuery'
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer