Bol Shipping Labels API

openapi: 3.2.0
info:
  title: v10 - Retailer Shipping Labels 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: Shipping Labels
  description: Shipping labels resource
paths:
  /retailer/shipping-labels:
    post:
      tags:
      - Shipping Labels
      summary: Create a shipping label
      description: Create a shipping label with a shipping label offer id retrieved from get delivery options.
      operationId: post-shipping-label
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/ShippingLabelRequest'
        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/shipping-labels/delivery-options:
    post:
      tags:
      - Shipping Labels
      summary: Get delivery options
      description: Retrieves all available delivery options based on the supplied configuration of order items that has to be shipped.
      operationId: get-delivery-options
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/DeliveryOptionsRequest'
        required: true
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/DeliveryOptionsResponse'
        '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/shipping-labels/{shipping-label-id}:
    get:
      tags:
      - Shipping Labels
      summary: Get a shipping label
      description: Retrieves a shipping label by shipping label id. Metadata for the shipping label is added as headers in the response. If you are only interested in the metadata, you can do a HEAD request to retrieve only the headers without the label data.
      operationId: get-shipping-label
      parameters:
      - name: shipping-label-id
        in: path
        description: The shipping label id.
        required: true
        schema:
          type: string
        example: 6ff736b5-cdd0-4150-8c67-78269ee986f5
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          headers:
            X-Track-And-Trace-Code:
              description: Track and trace code for the retrieved label.
              style: simple
              schema:
                type: string
            X-Transporter-Code:
              description: Transporter code for the retrieved label.
              style: simple
              schema:
                type: string
          content:
            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+pdf:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+pdf:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    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.
    DeliveryOption:
      required:
      - labelDisplayName
      - labelPrice
      - labelType
      - packageRestrictions
      - recommended
      - shippingLabelOfferId
      - transporterCode
      type: object
      properties:
        shippingLabelOfferId:
          type: string
          description: Unique identifier for the shipping label offer.
          example: 027b79fa-5743-40f0-94c7-0eac761af611
        recommended:
          type: boolean
          description: Indicates whether this delivery option is recommended to be the best option to ship your order item(s) with.
          example: true
        validUntilDate:
          type:
          - string
          - 'null'
          description: The date until the delivery option (incl total price) is valid.
          format: date
          example: '2020-01-12'
        transporterCode:
          type: string
          description: A code representing the transporter which is being used for transportation.
          example: TNT
        labelType:
          type: string
          description: The type of the label, representing the way an item is being transported. MAILBOX is a mailbox package with delivery scan. MAILBOX_LIGHT is a mailbox package without delivery scan. PARCEL is a normal package.
          example: PARCEL
          enum:
          - PARCEL
          - MAILBOX
          - MAILBOX_LIGHT
        labelDisplayName:
          type: string
          description: The display name of the shipping label.
          example: PostNL & bol.com - Pakket
        labelPrice:
          $ref: '#/components/schemas/LabelPrice'
        packageRestrictions:
          $ref: '#/components/schemas/PackageRestrictions'
        handoverDetails:
          allOf:
          - $ref: '#/components/schemas/HandoverDetails'
      description: A delivery option shows how and the costs of a transport for a shippable configuration
    DeliveryOptionsRequestOrderItem:
      required:
      - orderItemId
      type: object
      properties:
        orderItemId:
          minLength: 1
          type: string
          description: The id for the order item (1 order can have multiple order items).
          example: '2012345678'
        quantity:
          type:
          - integer
          - 'null'
          description: The quantity of the order item for which the shipping label creation is requested for. If omitted, will be interpreted as the full quantity that is still open for this order item.
          format: int32
          example: 1
          exclusiveMinimum: 0
      description: Order items for which the delivery options are requested.
    LabelPrice:
      required:
      - totalPrice
      type: object
      properties:
        totalPrice:
          type: number
          description: The price that is charged for this delivery option, excluding VAT.
          example: 2.88
    ShippingLabelRequest:
      required:
      - orderItems
      - shippingLabelOfferId
      type: object
      properties:
        orderItems:
          minItems: 1
          type: array
          description: Order items for which the delivery options are requested.
          items:
            $ref: '#/components/schemas/DeliveryOptionsRequestOrderItem'
        shippingLabelOfferId:
          minLength: 1
          type: string
          description: Shipping label offer id for which you request a shipping label.
          example: 027b79fa-5743-40f0-94c7-0eac761af611
      description: The configuration of order items to get delivery options for.
    DeliveryOptionsResponse:
      required:
      - deliveryOptions
      type: object
      properties:
        deliveryOptions:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryOption'
      description: The possible delivery options based on a shippable configuration
    HandoverDetails:
      type: object
      properties:
        meetsCustomerExpectation:
          type:
          - boolean
          - 'null'
          description: Indicates if you can use this label without receiving a strike if you handover before the latestHandoverDateTime. If this field is 'false' you can still buy and use this label but it will have negative consequences on your performance score because the order will be delivered too early or too late.
          example: true
        earliestHandoverDateTime:
          type:
          - string
          - 'null'
          description: The date and time at which the parcel can be earliest  at the transporter to make sure your parcel is delivered on time.
          format: date-time
          example: '2018-04-19T00:00:00+02:00'
        latestHandoverDateTime:
          type:
          - string
          - 'null'
          description: The date and time at which the parcel must ultimately be at the transporter to make sure your parcel is delivered on time. If you handover after this date you will receive a strike because you order will be delivered too late.
          format: date-time
          example: '2018-04-19T19:00:00+02:00'
        collectionMethod:
          type:
          - string
          - 'null'
          description: The type of collection for this parcel.
          example: DROP_OFF
          enum:
          - DROP_OFF
          - PICK_UP
          - null
    PackageRestrictions:
      required:
      - maxDimensions
      - maxWeight
      type: object
      properties:
        maxWeight:
          type: string
          description: The weight of a package.
          example: 10 kg
        maxDimensions:
          type: string
          description: The dimensions of a package.
          example: 10 x 10 x 10 cm
    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'
    DeliveryOptionsRequest:
      required:
      - orderItems
      type: object
      properties:
        orderItems:
          minItems: 1
          type: array
          description: Order items for which the delivery options are requested.
          items:
            $ref: '#/components/schemas/DeliveryOptionsRequestOrderItem'
      description: The configuration of order items to get delivery options for.
    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.
    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
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer