Bol Returns API

openapi: 3.2.0
info:
  title: v10 - Retailer Returns 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: Returns
  description: Return resource
paths:
  /retailer/returns:
    get:
      tags:
      - Returns
      summary: Get returns
      description: Get a paginated list of multi-item returns. Handled returns are sorted by date in descending order, while unhandled returns are sorted by date in ascending order.
      operationId: get-returns
      parameters:
      - name: page
        in: query
        description: The page to get with a page size of 50.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: handled
        in: query
        description: The status of the returns you wish to see, shows either handled or unhandled returns.
        required: false
        schema:
          type: boolean
      - name: fulfilment-method
        in: query
        description: The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
        required: false
        schema:
          type: string
          enum:
          - FBR
          - FBB
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ReturnsResponse'
        '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'
    post:
      tags:
      - Returns
      summary: Create a return
      description: Create a return, and automatically handle it with the provided handling result. When successfully created, the resulting return id is provided in the process status.
      operationId: create-return
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnRequest'
        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/returns/{return-id}:
    get:
      tags:
      - Returns
      summary: Get a return by return id
      description: Retrieve a return based on the return id.
      operationId: get-return
      parameters:
      - name: return-id
        in: path
        description: Unique identifier for a return.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Return'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /retailer/returns/{rma-id}:
    put:
      tags:
      - Returns
      summary: Handle a return by rma id
      description: Allows the user to handle a return. This can be to either handle an open return, or change the handlingResult of an already handled return. Please refer to the Returns documentation for further details.
      operationId: handle-return
      parameters:
      - name: rma-id
        in: path
        description: The RMA (Return Merchandise Authorization) identifier of the return.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/ReturnRequest'
        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'
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.
    ReturnProcessingResult:
      required:
      - handlingResult
      - processingDateTime
      - processingResult
      - quantity
      type: object
      properties:
        quantity:
          type: integer
          description: The processed quantity.
          format: int32
          example: 1
        processingResult:
          type: string
          description: The processing result of the return.
          example: ACCEPTED
        handlingResult:
          type: string
          description: The handling result requested by the retailer.
          example: RETURN_RECEIVED
        processingDateTime:
          type: string
          description: The date and time in ISO 8601 format when the return was processed.
          format: date-time
          example: '2018-04-17T10:55:37+02:00'
    ReturnsResponse:
      required:
      - returns
      type: object
      properties:
        returns:
          type: array
          items:
            $ref: '#/components/schemas/ReducedReturn'
    CreateReturnRequest:
      required:
      - handlingResult
      - orderItemId
      - quantityReturned
      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'
        quantityReturned:
          maximum: 9999
          minimum: 1
          type: integer
          description: The quantity of items returned.
          format: int32
          example: 1
        handlingResult:
          minLength: 1
          type: string
          description: The handling result requested by the retailer.
          example: RETURN_RECEIVED
          enum:
          - RETURN_RECEIVED
          - EXCHANGE_PRODUCT
          - RETURN_DOES_NOT_MEET_CONDITIONS
          - REPAIR_PRODUCT
          - CUSTOMER_KEEPS_PRODUCT_PAID
    ReturnRequest:
      required:
      - handlingResult
      - quantityReturned
      type: object
      properties:
        handlingResult:
          minLength: 1
          type:
          - string
          - 'null'
          description: The handling result requested by the retailer.
          example: RETURN_RECEIVED
          enum:
          - RETURN_RECEIVED
          - EXCHANGE_PRODUCT
          - RETURN_DOES_NOT_MEET_CONDITIONS
          - REPAIR_PRODUCT
          - CUSTOMER_KEEPS_PRODUCT_PAID
          - STILL_APPROVED
          - null
        quantityReturned:
          maximum: 9999
          minimum: 1
          type:
          - integer
          - 'null'
          description: The quantity of items returned.
          format: int32
          example: 1
      description: The handling result requested by the retailer.
    Return:
      required:
      - fulfilmentMethod
      - registrationDateTime
      - returnId
      - returnItems
      type: object
      properties:
        returnId:
          type: string
          description: Unique identifier for a return.
          example: '1'
        registrationDateTime:
          type: string
          description: The date and time in ISO 8601 format when this return was registered.
          format: date-time
          example: '2016-11-14T11:06:48.423+01:00'
        fulfilmentMethod:
          type: string
          description: The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
          example: FBR
        returnItems:
          type: array
          items:
            $ref: '#/components/schemas/ReturnItem'
    ReducedReturnItem:
      required:
      - ean
      - expectedQuantity
      - handled
      - orderId
      - processingResults
      - returnReason
      - rmaId
      type: object
      properties:
        rmaId:
          type: string
          description: The RMA (Return Merchandise Authorization) identifier of the return.
          example: '31234567'
        orderId:
          type: string
          description: The id of the customer order this return item is in.
          example: '4012345678'
        ean:
          type: string
          description: The EAN number associated with this product.
          example: '9789076174082'
        expectedQuantity:
          type: integer
          description: 'The quantity that is expected to be returned by the customer. Note: this can be greater than 1 in case the customer ordered a quantity greater than 1 of the same product in the same customer order.'
          format: int32
          example: 1
        returnReason:
          $ref: '#/components/schemas/ReturnReason'
        handled:
          type: boolean
          description: Indicates if this return item has been handled (by the retailer).
          example: true
        processingResults:
          type: array
          items:
            $ref: '#/components/schemas/ReturnProcessingResult'
    ReturnReason:
      required:
      - customerComments
      - mainReason
      type: object
      properties:
        mainReason:
          type: string
          description: The main reason describing why the customer returned this product.
          example: Niet naar verwachting
        detailedReason:
          type:
          - string
          - 'null'
          description: The sub reason describing why the customer returned this product in more detail.
          example: Niet naar verwachting
        customerComments:
          type: string
          description: Additional details from the customer as to why this item was returned.
          example: Lorem Ipsum
      description: "\nThe reason why the customer returned this product.\n\n- **mainReason** (required): The main reason describing why the customer returned this product.\n  Allowed values (examples): `Verkeerde maat of afmeting`, `Verkeerd besteld`\n\n- **detailedReason**: The sub reason describing why the customer returned this product in more detail.\n  Allowed values **depend on mainReason**:\n\n| mainReason                          | detailedReason values                                                                                                                                                                                 | comments                                                                                       |\n|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |------------------------------------------------------------------------------------------------|\n| Verkeerde maat of afmeting          | Te groot, Te klein, Artikel werkt niet op mijn apparatuur, Meerdere maten/afmetingen besteld, Aanbevolen accessoire past niet, Meerdere opties/artikelen besteld, Pasvorm valt tegen, Anders-namelijk | Optional customer text input                                                                   |\n| Verkeerd besteld                    | Onduidelijke productinformatie, Onduidelijke afbeelding, Dubbel besteld, Artikel had ik toch niet nodig, Aanbevolen accessoire past niet, Anders-namelijk                                             | Optional customer text input                                                                   |\n| Artikel werkt niet                  | -                                                                                                                                                                                                     | Optional customer text input                                                                   |\n| Klacht over artikel                 | Artikel is beschadigd, Artikel werkt niet, Artikel is incompleet, Kwaliteit valt tegen, Gebruiksaanwijzing onduidelijk, Artikel doet niet wat het belooft, Anders-namelijk                            | `customerComments` is mandatory only when \"Artikel werkt niet\" is selected. Otherwise Optional |\n| Klacht over de bezorging            | Artikel is te laat bezorgd, Verpakking is beschadigd, Artikel is beschadigd, Ander artikel ontvangen dan besteld, Anders-namelijk                                                                     | Optional customer text input                                                                   |\n| Elders goedkoper                    | -                                                                                                                                                                                                     | Optional customer text input                                                                   |\n| Ander artikel ontvangen dan besteld | Onduidelijke productinformatie, Onduidelijke afbeelding, Ander artikel ontvangen dan besteld                                                                                                          | Optional customer text input                                                                   |\n| Anders                              | Artikel cadeau ontvangen, Ik heb me bedacht, Artikel had ik toch niet nodig, Kwaliteit valt tegen, Andere kleur dan gedacht, Meerdere opties/artikelen besteld, Dubbel besteld, Anders-namelijk       | Optional customer text input                                                                   |\n|                                     |                                                                                                                                                                                                       |                                                                                                |\n- **customerComments** (required): Additional details from the customer about the return. Could be empty\n"
    ReducedReturn:
      required:
      - fulfilmentMethod
      - registrationDateTime
      - returnId
      - returnItems
      type: object
      properties:
        returnId:
          type: string
          description: Unique identifier for a return.
          example: '1'
        registrationDateTime:
          type: string
          description: The date and time in ISO 8601 format when this return was registered.
          format: date-time
          example: '2016-11-14T11:06:48.423+01:00'
        fulfilmentMethod:
          type: string
          description: The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
          example: FBR
        returnItems:
          type: array
          items:
            $ref: '#/components/schemas/ReducedReturnItem'
    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'
    CustomerDetails:
      required:
      - salutation
      type: object
      properties:
        salutation:
          type: string
          description: The salutation of the customer.
          example: MALE
          enum:
          - MALE
          - FEMALE
          - UNKNOWN
        firstName:
          type:
          - string
          - 'null'
          description: The first name of the customer.
          example: Billie
        surname:
          type:
          - string
          - 'null'
          description: The surname of the customer.
          example: Jansen
        streetName:
          type:
          - string
          - 'null'
          description: The street name.
          example: Dorpstraat
        houseNumber:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: The ZIP code in '1234AB' format for NL orders and '0000' format for BE orders.
          example: 1111ZZ
        city:
          type:
          - string
          - 'null'
          description: The name of the city.
          example: Utrecht
        countryCode:
          type:
          - string
          - 'null'
          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
        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'
        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
      description: Information related to the customer.
    ReturnItem:
      required:
      - customerDetails
      - ean
      - expectedQuantity
      - handled
      - orderId
      - processingResults
      - returnReason
      - rmaId
      - title
      type: object
      properties:
        rmaId:
          type: string
          description: The RMA (Return Merchandise Authorization) identifier of the return.
          example: '31234567'
        orderId:
          type: string
          description: The id of the customer order this return item is in.
          example: '4012345678'
        ean:
          type: string
          description: The EAN number associated with this product.
          example: '9789076174082'
        title:
          type: string
          description: The product title.
          example: Harry Potter en de steen der wijzen
        expectedQuantity:
          type: integer
          description: 'The quantity that is expected to be returned by the customer. Note: this can be greater than 1 in case the customer ordered a quantity greater than 1 of the same product in the same customer order.'
          format: int32
          example: 1
        returnReason:
          $ref: '#/components/schemas/ReturnReason'
        trackAndTrace:
          type:
          - string
          - 'null'
          description: The track and trace code that is associated with this transport.
          example: 3SBOL0987654321
        transporterName:
          type:
          - string
          - 'null'
          description: The name of the transporter.
          example: PostNL
        handled:
          type: boolean
          description: Indicates if this return item has been handled (by the retailer).
          example: true
        processingResults:
          type: array
          items:
            $ref: '#/components/schemas/ReturnProcessingResult'
        customerDetails:
          allOf:
          - $ref: '#/components/schemas/CustomerDetails'
    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