Bol Invoices API

openapi: 3.2.0
info:
  title: v10 - Retailer Invoices 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: Invoices
  description: Invoice resource
paths:
  /retailer/invoices:
    get:
      tags:
      - Invoices
      summary: Get all invoices
      description: 'Gets a list of invoices, by default from the past 4 weeks. The optional period-start-date and period-end-date-date parameters can be used together to retrieve invoices from a specific date range in the past, the period can be no longer than 31 days. Invoices and their specifications can be downloaded separately in different media formats with the ‘GET an invoice by id’ and the ‘GET an invoice specification by id’ calls. The available media types differ per invoice and are listed per invoice within the response. Note: the media types listed in the response must be given in our standard API format.'
      operationId: get-invoices
      parameters:
      - name: period-start-date
        in: query
        description: Period start date in ISO 8601 standard.
        required: false
        schema:
          type: string
        example: '2019-03-01'
      - name: period-end-date
        in: query
        description: Period end date in ISO 8601 standard.
        required: false
        schema:
          type: string
        example: '2019-03-31'
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                type: string
                format: byte
        '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/invoices/{invoice-id}:
    get:
      tags:
      - Invoices
      summary: Get an invoice by invoice id
      description: 'Gets an invoice by invoice id. The available media types differ per invoice and are listed within the response from the ‘GET all invoices’ call. Note: the media types listed in the response must be given in our standard API format.'
      operationId: get-invoice
      parameters:
      - name: invoice-id
        in: path
        description: The id of the invoice
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                type: string
                format: byte
            application/vnd.retailer.v10+pdf:
              schema:
                type: string
                format: byte
        '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'
            application/vnd.retailer.v10+pdf:
              schema:
                $ref: '#/components/schemas/Problem'
  /retailer/invoices/{invoice-id}/specification:
    get:
      tags:
      - Invoices
      summary: Get an invoice specification by invoice id
      description: Gets an invoice specification for an invoice with a paginated list of its transactions. The available media types differ per invoice specification and are listed within the response from the ‘GET all invoices’ call. Note, the media types listed in the response must be given in our standard API format.
      operationId: get-invoice-specification
      parameters:
      - name: invoice-id
        in: path
        description: The identifier of the invoice.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The requested page number with a maximum of 25,000 lines.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                type: string
                format: byte
            application/vnd.retailer.v10+openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: byte
        '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'
            application/vnd.retailer.v10+openxmlformats-officedocument.spreadsheetml.sheet:
              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'
            application/vnd.retailer.v10+openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    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.
    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.
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer