Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/bol-com:bol-com-offers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
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