Bol Orders API

openapi: 3.2.0
info:
  title: v10 - Retailer Orders 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: Orders
  description: Order resource
paths:
  /retailer/orders:
    get:
      tags:
      - Orders
      summary: Get a list of orders
      description: Gets a paginated list of all orders for a retailer.
      operationId: get-orders
      parameters:
      - name: page
        in: query
        description: The requested page number with a page size of 50 items.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: fulfilment-method
        in: query
        description: Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB). In order to retrieve both FBR and FBB orders, ALL can be used as a parameter.
        required: false
        schema:
          type: string
          default: FBR
          enum:
          - FBR
          - FBB
          - ALL
      - name: status
        in: query
        description: 'You can filter orders based on their status with the following options: all orders, which include every order regardless of its current status; open orders, which show only the active orders excluding those that have been shipped or cancelled; and shipped orders, which display only the orders that have been shipped.'
        required: false
        schema:
          type: string
          default: OPEN
          enum:
          - OPEN
          - SHIPPED
          - ALL
      - name: change-interval-minute
        in: query
        description: Indicate the period in minutes, to filter order items based on their most recent change. If this parameter value is included when polling the API, ensure your polling frequency is at least one minute shorter than the specified interval.For example, if change-interval-minute is set to 2 minutes, poll the API every 1 minute or less.
        required: false
        schema:
          maximum: 60
          type: integer
          format: int32
      - name: latest-change-date
        in: query
        description: To filter on the date on which the latest change was performed on an order item. Up to 3 months of history is supported.
        required: false
        schema:
          type: string
      - name: vvb-only
        in: query
        description: Filters results to include only orders fulfilled through VVB. If set to true, the API will return only VVB orders.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ReducedOrders'
  /retailer/orders/cancellation:
    put:
      tags:
      - Orders
      summary: Cancel an order item by an order item id
      description: This endpoint can be used to either confirm a cancellation request by the customer or to cancel an order item you yourself are unable to fulfil.
      operationId: cancel-order-item
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/CancellationRequest'
        required: true
      responses:
        '202':
          description: 'Accepted: Successfully scheduled the request for processing.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ProcessStatus'
        '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/orders/{order-id}:
    get:
      tags:
      - Orders
      summary: Get an order by order id
      description: Gets an order by order id. The order can be partially shipped or cancelled, and the message contains the quantity shipped or cancelled items.
      operationId: get-order
      parameters:
      - name: order-id
        in: path
        description: The id of the order to get.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean
    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.
    OrderFulfilment:
      required:
      - method
      - timeFrameType
      type: object
      properties:
        method:
          type: string
          description: The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
          example: FBR
        distributionParty:
          type:
          - string
          - 'null'
          description: The party that manages the distribution, either bol.com or the retailer itself.
          example: RETAILER
          enum:
          - RETAILER
          - BOL
          - null
        latestDeliveryDate:
          type:
          - string
          - 'null'
          description: The ultimate delivery date at which this order must be delivered at the customer's shipping address. This field is empty in case the exactDeliveryDate is filled.
          format: date
          example: '2017-02-10'
        exactDeliveryDate:
          type:
          - string
          - 'null'
          description: The exact delivery date at which this order must be delivered at the customer's shipping address. This field is only filled when the customer chose an exact date for delivery. This field is empty in case the latestDeliveryDate is filled.
          format: date
          example: '2017-02-13'
        expiryDate:
          type:
          - string
          - 'null'
          description: The date this order item will automatically expire and thereby cancelling this order item from the order.
          format: date
          example: '2017-02-13'
        timeFrameType:
          type: string
          description: Delivery option selected by the customer.
          example: REGULAR
          enum:
          - REGULAR
          - EVENING
          - APPOINTMENT
          - SAMEDAY
          - SUNDAY
    CancellationRequest:
      required:
      - orderItems
      type: object
      properties:
        orderItems:
          maxItems: 1
          minItems: 1
          type: array
          description: List of order items to cancel. Order item id's must belong to the same order.
          items:
            $ref: '#/components/schemas/OrderItemCancellation'
      description: Container for the order items that have to be cancelled.
    BillingDetails:
      required:
      - city
      - countryCode
      - email
      - firstName
      - houseNumber
      - salutation
      - streetName
      - surname
      - zipCode
      type: object
      properties:
        salutation:
          type: string
          description: The salutation of the customer.
          example: MALE
          enum:
          - MALE
          - FEMALE
          - UNKNOWN
        firstName:
          type: string
          description: The first name of the customer.
          example: Billie
        surname:
          type: string
          description: The surname of the customer.
          example: Jansen
        streetName:
          type: string
          description: The street name.
          example: Dorpstraat
        houseNumber:
          type: string
          description: The house number.
          example: '1'
        houseNumberExtension:
          type:
          - string
          - 'null'
          description: The extension on the house number.
          example: B
        extraAddressInformation:
          type:
          - string
          - 'null'
          description: Additional information related to the address that helps in delivering the package.
          example: Apartment
        zipCode:
          type: string
          description: The ZIP code in '1234AB' format for NL orders and '0000' format for BE orders.
          example: 1111ZZ
        city:
          type: string
          description: The name of the city.
          example: Utrecht
        countryCode:
          type: string
          description: The country code.
          example: NL
        email:
          type: string
          description: A scrambled email address that can be used to contact the customer.
          example: billie@verkopen.bol.com
        company:
          type:
          - string
          - 'null'
          description: The company name.
          example: bol.com
        vatNumber:
          type:
          - string
          - 'null'
          description: The Value Added Tax (VAT) / BTW number for business sellers situated in the Netherlands.
          example: NL999999999B99
        kvkNumber:
          type:
          - string
          - 'null'
          description: The Kamer van Koophandel (kvk) number for organizations situated in the Netherlands or ondernemingsnummer for organizations situated in Belgium.
          example: '99887766'
        orderReference:
          type:
          - string
          - 'null'
          description: The order reference specified by the customer when ordering a product.
          example: MijnReferentie
      description: The details of the customer that is responsible for the financial fulfillment of this order.
    AdditionalService:
      required:
      - serviceType
      type: object
      properties:
        serviceType:
          type: string
          description: An additional service type that the customer selected when purchasing this order item.
          example: PLACEMENT_AND_INSTALLATION
    ShipmentDetails:
      required:
      - city
      - countryCode
      - firstName
      - houseNumber
      - salutation
      - streetName
      - surname
      - zipCode
      type: object
      properties:
        pickupPointName:
          type:
          - string
          - 'null'
          description: The name of Pick Up Point location this order needs to be shipped to.
          example: 'Albert Heijn: UTRECHT'
        salutation:
          type: string
          description: The salutation of the customer.
          example: MALE
          enum:
          - MALE
          - FEMALE
          - UNKNOWN
        firstName:
          type: string
          description: The first name of the customer.
          example: Billie
        surname:
          type: string
          description: The surname of the customer.
          example: Jansen
        streetName:
          type: string
          description: The street name.
          example: Dorpstraat
        houseNumber:
          type: string
          description: The house number.
          example: '1'
        houseNumberExtension:
          type:
          - string
          - 'null'
          description: The extension on the house number.
          example: B
        extraAddressInformation:
          type:
          - string
          - 'null'
          description: Additional information related to the address that helps in delivering the package.
          example: Apartment
        zipCode:
          type: string
          description: The ZIP code in '1234AB' format for NL orders and '0000' format for BE orders.
          example: 1111ZZ
        city:
          type: string
          description: The name of the city.
          example: Utrecht
        countryCode:
          type: string
          description: The country code.
          example: NL
        email:
          type:
          - string
          - 'null'
          description: A scrambled email address that can be used to contact the customer.
          example: billie@verkopen.bol.com
        company:
          type:
          - string
          - 'null'
          description: The company name.
          example: bol.com
        deliveryPhoneNumber:
          type:
          - string
          - 'null'
          description: The delivery phone number of the customer. Filled in case the order requires an appointment for delivering the goods.
          example: '012123456'
        language:
          type:
          - string
          - 'null'
          description: The language of the customer in case of contact.
          example: nl
          enum:
          - nl, nl-BE, fr, fr-BE
          - null
      description: The address details where this order needs to be shipped to. This can be the customers' own address, a (company) business address or a Pick Up Point address.
    Discount:
      required:
      - amount
      - title
      type: object
      properties:
        title:
          type: string
          description: The title of the promotion.
          example: kiscier x + y promotion
        amount:
          type: number
          description: The discount price applied, including VAT.
          example: 10.99
    OrderProduct:
      required:
      - ean
      - title
      type: object
      properties:
        ean:
          type: string
          description: The EAN number associated with this product.
          example: '0000007740404'
        title:
          type: string
          description: Title of the product as shown on the webshop.
          example: Product Title
    Order:
      required:
      - orderId
      - orderItems
      - pickupPoint
      - shipmentDetails
      type: object
      properties:
        orderId:
          type: string
          description: The identifier of the order.
          example: A2K8290LP8
        pickupPoint:
          type: boolean
          description: Indicates whether this order is shipped to a Pick Up Point.
          example: true
        orderPlacedDateTime:
          type:
          - string
          - 'null'
          description: The date and time in ISO 8601 format when the order was placed.
          format: date-time
          example: '2017-02-09T12:39:48+01:00'
        shipmentDetails:
          $ref: '#/components/schemas/ShipmentDetails'
        billingDetails:
          allOf:
          - $ref: '#/components/schemas/BillingDetails'
        orderItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderOrderItem'
      description: An order.
    OrderOffer:
      type: object
      properties:
        offerId:
          type:
          - string
          - 'null'
          description: Unique identifier for an offer.
          example: 6ff736b5-cdd0-4150-8c67-78269ee986f5
        reference:
          type:
          - string
          - 'null'
          description: A user-defined reference that helps you identify this particular offer when receiving data from us. This element can optionally be left empty and has a maximum amount of 100 characters.
          example: BOLCOM00123
    OrderOrderItem:
      required:
      - cancellationRequest
      - commission
      - discounts
      - latestChangedDateTime
      - orderItemId
      - quantity
      - quantityCancelled
      - quantityShipped
      - totalPrice
      - unitPrice
      type: object
      properties:
        orderItemId:
          type: string
          description: The id for the order item. One order can have multiple order items, but the list can only take one item.
          example: '2012345678'
        cancellationRequest:
          type: boolean
          description: Indicates whether the order was cancelled on request of the customer before the retailer has shipped it.
          example: false
        fulfilment:
          allOf:
          - $ref: '#/components/schemas/OrderFulfilment'
        offer:
          allOf:
          - $ref: '#/components/schemas/OrderOffer'
        product:
          allOf:
          - $ref: '#/components/schemas/OrderProduct'
        quantity:
          type: integer
          description: Amount of ordered products for this order item id.
          format: int32
          example: 10
        quantityShipped:
          type: integer
          description: Amount of shipped products for this order item id.
          format: int32
          example: 10
        quantityCancelled:
          type: integer
          description: Amount of cancelled products for this order item id.
          format: int32
          example: 0
        unitPrice:
          type: number
          description: The selling price to the customer of a single unit including VAT.
          example: 12.99
        totalPrice:
          type: number
          description: The price the customer paid for the entirety of this item, including VAT.
          example: 118.91
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        commission:
          type: number
          description: The commission for all quantities of this order item.
          example: 5.18
        additionalServices:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AdditionalService'
        latestChangedDateTime:
          type:
          - string
          - 'null'
          description: The date and time in ISO 8601 format when the orderItem was last changed.
          format: date-time
          example: '2017-02-09T13:39:48+01:00'
      description: Order item details from an order.
    ReducedOrderItem:
      required:
      - cancellationRequest
      - ean
      - fulfilmentMethod
      - fulfilmentStatus
      - latestChangedDateTime
      - orderItemId
      - quantity
      - quantityCancelled
      - quantityShipped
      type: object
      properties:
        orderItemId:
          type: string
          description: The id for the order item. One order can have multiple order items, but the list can only take one item.
          example: '2012345678'
        ean:
          type: string
          description: The EAN number associated with this product.
          example: '0000007740404'
        fulfilmentMethod:
          type: string
          description: The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
          example: FBR
          enum:
          - FBR
          - FBB
        fulfilmentStatus:
          type: string
          description: 'This field indicates the processing state of an order. It can have two values: "OPEN," which corresponds to active order items excluding those that have been shipped or cancelled, and "HANDLED," which means the order item has either been shipped or cancelled.'
          example: OPEN
          enum:
          - OPEN
          - HANDLED
        quantity:
          type: integer
          description: Amount of ordered products for this order item id.
          format: int32
          example: 10
        quantityShipped:
          type: integer
          description: Amount of shipped products for this order item id.
          format: int32
          example: 10
        quantityCancelled:
          type: integer
          description: Amount of cancelled products for this order item id.
          format: int32
          example: 0
        cancellationRequest:
          type: boolean
          description: Indicates whether the order was cancelled on request of the customer before the retailer has shipped it.
          example: false
        latestChangedDateTime:
          type:
          - string
          - 'null'
          description: The date and time in ISO 8601 format when the orderItem was last changed.
          format: date-time
          example: '2017-02-09T12:39:48+01:00'
      description: An order item.
    ReducedOrder:
      required:
      - orderId
      - orderItems
      - orderPlacedDateTime
      type: object
      properties:
        orderId:
          type: string
          description: The identifier of the order.
          example: A2K8290LP8
        orderPlacedDateTime:
          type:
          - string
          - 'null'
          description: The date and time in ISO 8601 format when the order was placed.
          format: date-time
          example: '2017-02-09T12:39:48+01:00'
        orderItems:
          type: array
          items:
            $ref: '#/components/schemas/ReducedOrderItem'
      description: An order.
    ProcessStatus:
      required:
      - createTimestamp
      - description
      - eventType
      - links
      - status
      type: object
      properties:
        processStatusId:
          type:
          - string
          - 'null'
          description: The process status id.
          example: '1234567'
        entityId:
          type:
          - string
          - 'null'
          description: The id of the object being processed. For example, in case of a shipment process id, you will receive the id of the order item being processed.
          example: '987654321'
        eventType:
          type: string
          description: Name of the requested action that is being processed.
          example: CREATE_SHIPMENT
        description:
          type: string
          description: Describes the action that is being processed.
          example: Example process status description for processing 987654321.
        status:
          type: string
          description: Status of the action being processed.
          example: SUCCESS
          enum:
          - PENDING
          - SUCCESS
          - FAILURE
          - TIMEOUT
        errorMessage:
          type:
          - string
          - 'null'
          description: Shows error message if applicable.
          example: Example process status error message.
        createTimestamp:
          type: string
          description: Time of creation of the response.
          format: date-time
          example: '2018-11-14T09:34:41+01:00'
        links:
          type: array
          description: Lists available actions applicable to this endpoint.
          items:
            $ref: '#/components/schemas/Link'
    OrderItemCancellation:
      required:
      - orderItemId
      - reasonCode
      type: object
      properties:
        orderItemId:
          minLength: 1
          type: string
          description: The id for the order item. One order can have multiple order items, but the list can only take one item.
          example: '2012345678'
        reasonCode:
          minLength: 1
          type: string
          description: The code representing the reason for cancellation of this item.
          example: BAD_CONDITION
          enum:
          - OUT_OF_STOCK, REQUESTED_BY_CUSTOMER, BAD_CONDITION, HIGHER_SHIPCOST, INCORRECT_PRICE, NOT_AVAIL_IN_TIME, NO_BOL_GUARANTEE, ORDERED_TWICE, RETAIN_ITEM, TECH_ISSUE, UNFINDABLE_ITEM, OTHER
      description: List of order items to cancel. Order item id's must belong to the same order.
    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.
    ReducedOrders:
      required:
      - orders
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/ReducedOrder'
      description: Container for many orders.
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer