Bol Offers API

openapi: 3.2.0
info:
  title: v10 - Retailer Offers 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: Offers
  description: Offer resource
paths:
  /retailer/offers:
    post:
      tags:
      - Offers
      summary: Create a new offer
      description: Creates a new offer, and adds it to the catalog. After creation, status information can be retrieved to review if the offer is valid and published to the shop.
      operationId: post-offer
      parameters:
      - name: X-Fulfilment-Party
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/CreateOfferRequest'
        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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/export:
    post:
      tags:
      - Offers
      summary: Request an offer export file
      description: Request an offer export file containing all offers.
      operationId: post-offer-export
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/CreateOfferExportRequest'
        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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/export/{report-id}:
    get:
      tags:
      - Offers
      summary: Retrieve an offer export file by report id
      description: Retrieve an offer export file containing all offers.
      operationId: get-offer-export
      parameters:
      - name: report-id
        in: path
        description: Unique identifier for an offer export file.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
        '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+csv:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+csv:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/unpublished:
    post:
      tags:
      - Offers
      summary: Request an unpublished offer report
      description: Request an unpublished offer report containing all unpublished offers and reasons.
      operationId: post-unpublished-offer-report
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/CreateUnpublishedOfferReportRequest'
        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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/unpublished/{report-id}:
    get:
      tags:
      - Offers
      summary: Retrieve an unpublished offer report by report id
      description: Retrieve an unpublished offer report containing all unpublished offers and reasons.
      operationId: get-unpublished-offer-report
      parameters:
      - name: report-id
        in: path
        description: Unique identifier for unpublished offer report.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
        '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+csv:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+csv:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/{offer-id}:
    get:
      tags:
      - Offers
      summary: Retrieve an offer by its offer id
      description: Retrieve an offer by using the offer id provided to you when creating or listing your offers.
      operationId: get-offer
      parameters:
      - name: offer-id
        in: path
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/RetailerOffer'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
    put:
      tags:
      - Offers
      summary: Update an offer
      description: Use this endpoint to send an offer update. This endpoint returns a process status.
      operationId: put-offer
      parameters:
      - name: offer-id
        in: path
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/UpdateOfferRequest'
        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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
    delete:
      tags:
      - Offers
      summary: Delete offer by id
      description: Delete an offer by id.
      operationId: delete-offer
      parameters:
      - name: offer-id
        in: path
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/{offer-id}/price:
    put:
      tags:
      - Offers
      summary: Update price(s) for offer by id
      description: Update price(s) for offer by id.
      operationId: update-offer-price
      parameters:
      - name: offer-id
        in: path
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/UpdateOfferPriceRequest'
        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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/offers/{offer-id}/stock:
    put:
      tags:
      - Offers
      summary: Update stock for offer by id
      description: Update stock for offer by id.
      operationId: update-offer-stock
      parameters:
      - name: offer-id
        in: path
        description: Unique identifier for an offer.
        required: true
        schema:
          type: string
      - name: X-Fulfilment-Party
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/UpdateOfferStockRequest'
        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'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
components:
  schemas:
    NotPublishableReason:
      required:
      - code
      - description
      type: object
      properties:
        code:
          type: string
          description: Error code signalling that the offer is invalid.
          example: '4003'
        description:
          type: string
          description: Error message describing the reason the offer is invalid.
          example: The seller is on holiday.
    CreateOfferExportRequest:
      required:
      - format
      type: object
      properties:
        format:
          minLength: 1
          type: string
          description: The file format in which to return the export.
          example: CSV
          enum:
          - CSV
    Stock:
      required:
      - managedByRetailer
      type: object
      properties:
        amount:
          type:
          - integer
          - 'null'
          description: 'The amount of stock available for the specified product present in the retailers warehouse. Note: this should not be the FBB stock! Defaults to 0.'
          format: int32
          example: 6
        correctedStock:
          type:
          - integer
          - 'null'
          description: The amount of order items in stock minus handled order items and minus open order items. As compared to the stock you sent us. When this reaches 0, your offer will not be for sale on the shop.
          format: int32
          example: 5
        managedByRetailer:
          type: boolean
          description: Configures whether the retailer manages the stock levels or that bol.com should calculate the corrected stock based on actual open orders. In case the configuration is set to 'false', all open orders are used to calculate the corrected stock. In case the configuration is set to 'true', only orders that are placed after the last offer update are taken into account.
          example: false
    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.
    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'
    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
    OffersCountryCode:
      required:
      - countryCode
      type: object
      properties:
        countryCode:
          type: string
          description: Countries in which this offer is currently on sale in the webshop, in ISO-3166-1 format.
          example: NL
    Store:
      required:
      - visible
      type: object
      properties:
        productTitle:
          type:
          - string
          - 'null'
          description: The product title for the product associated with this offer.
          example: Product Title
        visible:
          type: array
          items:
            $ref: '#/components/schemas/OffersCountryCode'
    StockCreate:
      required:
      - amount
      - managedByRetailer
      type: object
      properties:
        amount:
          maximum: 999
          minimum: 0
          type:
          - integer
          - 'null'
          description: 'The amount of stock available for the specified product present in the retailers warehouse. Note: this should not be the FBB stock! Defaults to 0.'
          format: int32
          example: 6
        managedByRetailer:
          type:
          - boolean
          - 'null'
          description: Configures whether the retailer manages the stock levels or that bol.com should calculate the corrected stock based on actual open orders. In case the configuration is set to 'false', all open orders are used to calculate the corrected stock. In case the configuration is set to 'true', only orders that are placed after the last offer update are taken into account.
          example: false
    CreateOfferRequest:
      required:
      - condition
      - ean
      - fulfilment
      - pricing
      - stock
      type: object
      properties:
        ean:
          minLength: 1
          type:
          - string
          - 'null'
          description: 'The EAN number associated with this product. Note: in case an ISBN is provided, the ISBN will be replaced with the actual EAN belonging to this ISBN.'
          example: '0000007740404'
        economicOperatorId:
          type:
          - string
          - 'null'
          description: An identifier referring to the Economic operator entity (manufacturer, authorized party, importer, distributor or other natural person or legal entity for whom the obligations apply with regards to the manufacturing, or making available on the market of the product in line with the applicable EU laws).
          example: 90bfddc5-a6d0-4986-9253-407b3a6850ca
        condition:
          allOf:
          - $ref: '#/components/schemas/Condition'
        reference:
          maxLength: 100
          minLength: 0
          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: REF12345
        onHoldByRetailer:
          type: boolean
          description: This field specifies whether the retailer has temporarily suspended the listing of this offer on the bol.com website. When set to true, the offer becomes invisible to customers and is not available for purchase. The default setting, false, indicates that the offer is active and visible on the website. This feature is useful for managing inventory or making updates to the offer without permanently removing it from the site.
          example: false
          default: false
        unknownProductTitle:
          maxLength: 500
          minLength: 0
          type:
          - string
          - 'null'
          description: 'In case the item is not known to bol.com you can use this field to identify this particular product. Note: in case the product is known to bol.com, the unknown product title will not be stored.'
          example: Unknown Product Title
        pricing:
          allOf:
          - $ref: '#/components/schemas/Pricing'
        stock:
          allOf:
          - $ref: '#/components/schemas/StockCreate'
        fulfilment:
          allOf:
          - $ref: '#/components/schemas/Fulfilment'
    Fulfilment:
      required:
      - method
      type: object
      properties:
        method:
          minLength: 1
          type:
          - string
          - 'null'
          description: The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
          example: FBR
          enum:
          - FBR
          - FBB
          - null
        deliveryCode:
          type:
          - string
          - 'null'
          description: The delivery promise that applies to this offer. This value will only be used in combination with fulfilmentMethod 'FBR'.
          enum:
          - 24uurs-23
          - 24uurs-22
          - 24uurs-21
          - 24uurs-20
          - 24uurs-19
          - 24uurs-18
          - 24uurs-17
          - 24uurs-16
          - 24uurs-15
          - 24uurs-14
          - 24uurs-13
          - 24uurs-12
          - 1-2d
          - 2-3d
          - 3-5d
          - 4-8d
          - 1-8d
          - MijnLeverbelofte
          - VVB
          - null
        profileId:
          type:
          - string
          - 'null'
          description: Profile ID reference used for custom fulfillment options.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    Condition:
      required:
      - name
      type: object
      properties:
        name:
          minLength: 1
          type:
          - string
          - 'null'
          description: The condition of the offered product.
          example: AS_NEW
          enum:
          - NEW
          - AS_NEW
          - GOOD
          - REASONABLE
          - MODERATE
          - null
        category:
          type:
          - string
          - 'null'
          description: The category of the condition. If not given NEW or SECONDHAND is derived from NAME.
          example: SECONDHAND
          enum:
          - NEW
          - SECONDHAND
          - null
        comment:
          maxLength: 2000
          minLength: 0
          type:
          - string
          - 'null'
          description: The description of the condition of the product. Only allowed if name is not NEW and may not contain e-mail addresses.
          example: Heeft een koffie vlek op de kaft.
    RetailerOffer:
      required:
      - condition
      - ean
      - fulfilment
      - notPublishableReasons
      - offerId
      - onHoldByRetailer
      - pricing
      - stock
      - store
      type: object
      properties:
        offerId:
          type: string
          description: Unique identifier for an offer.
          example: 6ff736b5-cdd0-4150-8c67-78269ee986f5
        ean:
          type: string
          description: 'The EAN number associated with this product. Note: in case an ISBN is provided, the ISBN will be replaced with the actual EAN belonging to this ISBN.'
          example: '0000007740404'
        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: REF12345
        onHoldByRetailer:
          type: boolean
          description: This field specifies whether the retailer has temporarily suspended the listing of this offer on the bol.com website. When set to true, the offer becomes invisible to customers and is not available for purchase. The default setting, false, indicates that the offer is active and visible on the website. This feature is useful for managing inventory or making updates to the offer without permanently removing it from the site.
          example: false
        economicOperatorId:
          type:
          - string
          - 'null'
          description: An identifier referring to the Economic operator entity (manufacturer, authorized party, importer, distributor or other natural person or legal entity for whom the obligations apply with regards to the manufacturing, or making available on the market of the product in line with the applicable EU laws).
          example: 90bfddc5-a6d0-4986-9253-407b3a6850ca
        unknownProductTitle:
          type:
          - string
          - 'null'
          description: 'In case the item is not known to bol.com you can use this field to identify this particular product. Note: in case the product is known to bol.com, the unknown product title will not be stored.'
          example: Unknown Product Title
        pricing:
          $ref: '#/components/schemas/Pricing'
        stock:
          $ref: '#/components/schemas/Stock'
        fulfilment:
          $ref: '#/components/schemas/Fulfilment'
        store:
          $ref: '#/components/schemas/Store'
        condition:
          $ref: '#/components/schemas/Condition'
        notPublishableReasons:
          type: array
          items:
            $ref: '#/components/schemas/NotPublishableReason'
    Pricing:
      required:
      - bundlePrices
      type: object
      properties:
        bundlePrices:
          maxItems: 4
          minItems: 1
          type: array
          description: A set of prices (containing a quantity and selling price) that apply to this offer.
          items:
            $ref: '#/components/schemas/BundlePrice'
    UpdateOfferPriceRequest:
      required:
      - pricing
      type: object
      properties:
        pricing:
          allOf:
          - $ref: '#/components/schemas/Pricing'
    CreateUnpublishedOfferReportRequest:
      required:
      - format
      type: object
      properties:
        format:
          minLength: 1
          type: string
          description: The file format in which to return the export.
          example: CSV
          enum:
          - CSV
    BundlePrice:
      required:
      - quantity
      - unitPrice
      type: object
      properties:
        quantity:
          maximum: 24
          minimum: 1
          type:
          - integer
          - 'null'
          description: The minimum quantity a customer must order in order to receive discount. The element with value 1 must at least be present. In case of using more elements, the respective quantities must be in increasing order.
          format: int32
          example: 1
        unitPrice:
          maximum: 9999
          minimum: 1
          type:
          - number
          - 'null'
          description: The price per single unit including VAT in case the customer orders at least the quantity provided. When using more than 1 price, the respective prices must be in decreasing order using 2 decimal precision and dot separated.
          example: 9.99
      description: A set of prices (containing a quantity and selling price) that apply to this offer.
    UpdateOfferRequest:
      required:
      - fulfilment
      type: object
      properties:
        economicOperatorId:
          type:
          - string
          - 'null'
          description: An identifier referring to the Economic operator entity (manufacturer, authorized party, importer, distributor or other natural person or legal entity for whom the obligations apply with regards to the manufacturing, or making available on the market of the product in line with the applicable EU laws).
          example: 90bfddc5-a6d0-4986-9253-407b3a6850ca
        reference:
          maxLength: 100
          minLength: 0
          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: REF12345
        onHoldByRetailer:
          type: boolean
          description: This field specifies whether the retailer has temporarily suspended the listing of this offer on the bol.com website. When set to true, the offer becomes invisible to customers and is not available for purchase. The default setting, false, indicates that the offer is active and visible on the website. This feature is useful for managing inventory or making updates to the offer without permanently removing it from the site.
          example: false
          default: false
        unknownProductTitle:
          maxLength: 500
          minLength: 0
          type:
          - string
          - 'null'
          description: 'In case the item is not known to bol.com you can use this field to identify this particular product. Note: in case the product is known to bol.com, the unknown product title will not be stored.'
          example: Unknown Product Title
        fulfilment:
          allOf:
          - $ref: '#/components/schemas/Fulfilment'
    UpdateOfferStockRequest:
      required:
      - amount
      - managedByRetailer
      type: object
      properties:
        amount:
          maximum: 999
          minimum: 0
          type:
          - integer
          - 'null'
          description: 'The amount of stock available for the specified product present in the retailers warehouse. Note: this should not be the FBB stock! Defaults to 0.'
          format: int32
          example: 6
        managedByRetailer:
          type:
          - boolean
          - 'null'
          description: Configures whether the retailer manages the stock levels or that bol.com should calculate the corrected stock based on actual open orders. In case the configuration is set to 'false', all open orders are used to calculate the corrected stock. In case the configuration is set to 'true', only orders that are placed after the last offer update are taken into account.
          example: false
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer