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-promotions-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 Promotions 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: Promotions
description: Promotions resource
paths:
/retailer/promotions:
get:
tags:
- Promotions
summary: Get a list of promotions
description: Gets a paginated list of all promotions for a retailer.
operationId: get-promotions
parameters:
- name: promotion-type
in: query
description: The type(s) of promotion to be retrieved.
required: true
schema:
type: string
enum:
- AWARENESS
- PRICE_OFF
- name: page
in: query
description: The requested page number with a page size of 50 items.
required: false
schema:
minimum: 1
type: integer
format: int32
default: 1
example: 1
responses:
'200':
description: 'Ok: Successfully processed the request.'
content:
application/vnd.retailer.v10+json:
schema:
$ref: '#/components/schemas/Promotions'
'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/promotions/{promotion-id}:
get:
tags:
- Promotions
summary: Get a promotion by promotion id
description: Gets the details of a promotion.
operationId: get-promotion
parameters:
- name: promotion-id
in: path
description: The identifier of the promotion.
required: true
schema:
type: string
responses:
'200':
description: 'Ok: Successfully processed the request.'
content:
application/vnd.retailer.v10+json:
schema:
$ref: '#/components/schemas/Promotion'
'404':
description: 'Not found: The requested item could not be found.'
content:
application/vnd.retailer.v10+json:
schema:
$ref: '#/components/schemas/Problem'
'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/promotions/{promotion-id}/products:
get:
tags:
- Promotions
summary: Get a list of products
description: Gets a paginated list of all products that are present within a promotion.
operationId: get-products
parameters:
- name: promotion-id
in: path
description: The identifier of the promotion.
required: true
schema:
type: string
- name: page
in: query
description: The requested page number with a page size of 50 items.
required: false
schema:
minimum: 1
type: integer
format: int32
default: 1
example: 1
responses:
'200':
description: 'Ok: Successfully processed the request.'
content:
application/vnd.retailer.v10+json:
schema:
$ref: '#/components/schemas/Products'
'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:
Promotion:
required:
- countries
- endDateTime
- promotionId
- promotionType
- retailerSpecificPromotion
- startDateTime
- title
type: object
properties:
promotionId:
type: string
description: The identifier of the promotion.
example: '1234'
title:
type: string
description: The title of the promotion.
example: Promotion title
startDateTime:
type: string
description: The starting date and time of the promotion.
format: date-time
example: '2021-03-29T00:00:00+02:00'
endDateTime:
type: string
description: The ending date and time of the promotion.
format: date-time
example: '2021-05-10T00:00:00+02:00'
countries:
type: array
items:
$ref: '#/components/schemas/PromotionCountryCode'
promotionType:
type: string
description: The type of the promotion.
example: AWARENESS
enum:
- AWARENESS
- PRICE_OFF
retailerSpecificPromotion:
type: boolean
description: Indicates whether the promotion is retailer specific or open to the platform.
example: false
campaign:
allOf:
- $ref: '#/components/schemas/Campaign'
description: A single promotion.
Campaign:
required:
- name
- startDateTime
type: object
properties:
name:
type: string
description: The name of the campaign under which the promotion had been created.
example: Campaign name
startDateTime:
type: string
description: The starting date and time of the campaign.
format: date-time
example: '2021-03-29T00:00:00+02:00'
endDateTime:
type:
- string
- 'null'
description: The ending date and time of the campaign.
format: date-time
example: '2021-05-10T00:00:00+02:00'
PromotionCountryCode:
required:
- countryCode
type: object
properties:
countryCode:
type: string
description: The country code of the country in which the promotion is active.
example: NL
enum:
- NL
- BE
Promotions:
type: object
properties:
promotions:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ReducedPromotion'
description: Container for multiple promotions.
Product:
required:
- ean
type: object
properties:
ean:
type: string
description: The EAN number associated with this product.
example: '0000007740404'
relevanceScores:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/RelevanceScore'
maximumPrice:
type:
- number
- 'null'
description: The maximum price a product can have in order to be part of the promotion.
example: 21.5
description: A single product.
ReducedPromotion:
required:
- countries
- endDateTime
- promotionId
- promotionType
- retailerSpecificPromotion
- startDateTime
- title
type: object
properties:
promotionId:
type: string
description: The identifier of the promotion.
example: '1234'
title:
type: string
description: The title of the promotion.
example: Promotion title
startDateTime:
type: string
description: The starting date and time of the promotion.
format: date-time
example: '2021-03-29T00:00:00+02:00'
endDateTime:
type: string
description: The ending date and time of the promotion.
format: date-time
example: '2021-05-10T00:00:00+02:00'
countries:
type: array
items:
$ref: '#/components/schemas/PromotionCountryCode'
promotionType:
type: string
description: The type of the promotion.
example: AWARENESS
enum:
- AWARENESS
- PRICE_OFF
retailerSpecificPromotion:
type: boolean
description: Indicates whether the promotion is retailer specific or open to the platform.
example: false
campaign:
allOf:
- $ref: '#/components/schemas/Campaign'
description: A single promotion.
RelevanceScore:
type: object
properties:
countryCode:
type:
- string
- 'null'
description: The country for which the relevance score has been calculated against.
example: NL
enum:
- NL
- BE
- null
relevanceScore:
type:
- integer
- 'null'
description: The calculated relevance score for the product.
format: int32
example: 72
enum:
- null
description: The relevance score of a product in a promotion.
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.
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.
Products:
required:
- products
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
description: Container for multiple products.
securitySchemes:
OAuth2:
type: http
description: JWT-based access to api.bol.com
in: header
scheme: bearer