We are currently experiencing an issue when creating shipments through the API. When processing an order, you may receive the following error:

Request contains unknown order item id(s): [xxxxxxx]. Possible reasons: order item(s) do not exist or order item(s) cannot be fulfilled by the retailer (only FBR items can be fulfilled).

This error message is incorrect. Despite the response, the shipment is actually processed successfully. Our team is investigating the root cause of this issue. We will provide an update as soon as more information is available.

We apologise for the inconvenience.

Update 10:15

The Get shipment, Get order endpoints and the seller account return the correct and up-to-date status. We recommend using these endpoints to verify the current status of your orders.

Update 12:00

The issue is seems fixed for most merchants, and the impact is minor. Only a few merchants are affected. We are looking at the root cause for these merchants.

We are happy to announce that one of the most requested features is now available: Order Subscriptions.

What are Order Subscriptions?
With Order Subscriptions, bol automatically sends a notification whenever an order is created or changed. This means you no longer need to continuously poll the Order API.

The benefits of Order Subscriptions:

• Real‑time order updates
  Receive instant notifications as soon as an order is created or changed, without delays caused by polling intervals.
• Faster order processing
  Orders can be picked up and processed immediately, resulting in shorter handling times and faster fulfilment.
• Reduced risk of missed cancellations
  Real-time notifications make it less likely that customer cancellation requests are overlooked, helping prevent unnecessary shipments.
• No more continuous polling
  Order Subscriptions eliminate the need to repeatedly call the API to check for updates, making integrations more efficient and easier to maintain.
• Lower API load and improved overall platform stability
  Fewer API calls reduce infrastructure usage on your side and contribute to improved overall platform stability of bol.
  

How to get started

• Do you have your own integration?
  All functional and technical details are available in the Subscriptions documentation.
• Do you work with an integration partner?
  Contact your integration partner to check whether they will support Order Subscriptions. Several parties within the Apps & Dienstverleners network will start supporting this feature soon.

This is a reminder that the format of processStatusId will change on May 12.
Make sure to review the upcoming change and verify whether your integration is affected.

Read the full announcement here.

It appears that there is currently an issue with creating VVB labels for some retailers. We are investigating this at the moment.

We will share an update as soon as more information is available.

Update

We have identified the affected orders where VVB shipping labels could not be downloaded. This impacts approximately 1,100 orders.

We are reprocessing these orders so new transport options are assigned and labels can be created again. Please note that some orders may be marked as late after reprocessing.

Update

We still see issues with a few orders and are currently investigating the root cause.

Update 15:30
All affected orders will be reprocessed within the next 20 minutes. For API users, the following steps are required after reprocessing:

• Retrieve the delivery options again for the affected orders
• Select a delivery option that is not delivered by Ampere
• Download a new shipping label

Partners will not receive strikes for the affected orders.

We apologize for the inconvenience.

Update 23-04-2026

As mentioned in our latest update, all open orders have been processed, and we have closed this incident.

This is a reminder that the format of processStatusId will change on May 12.
Make sure to review the upcoming change and verify whether your integration is affected.

Read the full announcement here.

On Tuesday, April 14, 2026, planned maintenance is scheduled between 06:00 and 07:00 CET, causing approximately 10 minutes of downtime.

During this time:

• Newly placed FBR orders will not be delivered.
• Customer cancellation requests (FBR and FBB) will not be delivered.

Orders and cancellation requests placed during the downtime will become available again after the maintenance window.

Sorry for the inconvenience.

Update

The maintenance was completed successfully this morning. All services are working normally again.

We are currently experiencing an increased number of 503/ 504 errors. If you encounter a 503/ 504 error, please retry your request. Our team is investigating the underlying cause and working to resolve the issue. We apologise for any inconvenience this may cause.

Update 15:32: The issue has been mitigated. We will continue to monitor the situation closely.

Starting 15 April, bol will automatically add the deposit (statiegeld) to the sales price on the product page and during checkout for soft drinks.

To avoid pricing issues, please remove the deposit amount from your current sales prices for any applicable items sold via bol on 15 April.

Additionally, all relevant product attributes must be completed accurately. Please ensure the following attributes are filled in for your items:

• Deposit (Statiegeld)
• Packaging type (Verpakkingsvorm)
• Number of units per package (Aantal stuks in verpakking)
• Content per unit (Inhoud per eenheid)

You can update these details now, ahead of 15 April.

If any of the required deposit-related attributes are missing, the affected items may be taken offline.

We recommend reviewing and updating your assortment as soon as possible to ensure a smooth transition.

For more details, please visit our Partnerplatform.

Between 15:30 and 16:05 (CET), our async content processes experienced downtime, which may have caused async content requests to fail or remain unprocessed. The underlying issue has been fixed, and processing is back to normal.

Please re-run any async content requests submitted during the affected window to ensure they are processed successfully.

Sorry for the inconvenience.

On March 21, between 10:00 a.m. and 12:00 p.m., we will be performing scheduled maintenance. During this window, there will be 5 to 10 minutes of downtime. During the downtime, it will not be possible to retrieve shipping labels for orders shipped via Verzenden via bol (Vvb). Once the maintenance is completed, all shipping labels will be available again.

Thank you for your understanding, and we apologize for any inconvenience this may cause.

On March 24, we will release an update that improves the visibility of error responses.
Starting from this date, the X‑Request‑ID—already available in the response headers since March 4—will also be included as a dedicated field in all error response messages.

If you need support with an erroneous API call, you can share this X‑Request‑ID with Partner Service. It enables them to quickly locate the specific request and provide faster, more accurate assistance.

For successful API calls, you can continue to provide the X‑Request‑ID from the response header if you have any follow‑up questions.

To keep our platform safe and reliable, we'll start taking items missing specific legally required product information offline in phases from 1 April, as previously announced.

On this page, you will find the product groups for the coming period. If this affects your product range, you’ll also see a banner in your bol seller account. Please note! If you have seen this message before, it applies to a different product group this time. Add the missing information now to keep your items online.

What information is required?

• Manufacturer details (most items)
  Manufacturer Name/Address/Email or electronic address
  Read more
• Energy label and product data sheet (many devices and appliances)
  This includes washing machines, fridges, televisions, tablets, and other energy-related products.
  Read more
• Extra information for connected devices
  Such as robot vacuums, smart lights, smartwatches, baby monitors, thermostats, and more.
  Read more

More information
Read more about European laws and regulations for selling via bol. This page is informative and does not contain any legal advice; partners are responsible for their own compliance.

We are currently investigating an incident related to the Retailer API and bol webshop with emergency priority.

Update 18:11: The issue has been mitigated. We will continue to monitor the situation closely.

Discover new sales opportunities even faster and more easily

After a successful pilot, the renewed white spots list is now live. White spots are items that customers search for on bol but that are not yet sold on our platform. By adding these items to your assortment, you respond directly to customer demand and increase your sales opportunities.

What’s new?

Based on feedback from partners, we improved the white spots list. The list now includes:

• Smarter suggestions
  The suggestions now match your assortment even better. We no longer only look at the category you sell in, but also at the brands. This helps filter out brands for which you do not have selling rights.
• Better filters
  The filters now work at a higher category level. This improves the quality of the filtering and helps you find more relevant results than before.
• Renewed potential score
  The potential score now shows more clearly where the biggest sales opportunities are. The score is based on current customer demand and highlights the items that are most interesting to add to your assortment.

Also new: exporting

Many partners asked for an export feature, so we added one. You can now export up to 10,000 items based on the filters you use. This is useful if you work with the API or manage your assortment outside your seller account.

With these improvements, it becomes easier to discover relevant opportunities and add new assortment faster. You can find your personal white spots in your seller account. If you want to explore the full list, you can also find it on the Partner Platform.

We would like to inform you about scheduled maintenance taking place on 12 March, between 06:00 and 07:00 AM.
During this window, certain functionalities will be temporarily affected.

Customer cancellations

• Customer cancellations will not be visible.
• Customer‑initiated cancellations will not be forwarded.

Incomplete shipping confirmations for FBR orders

• Shipping confirmations may be missing or incomplete.
• Essential shipment data (e.g., transportId) may be absent.

Incomplete shipment information

• Shipments may appear with empty or missing fields.
• API responses may also contain incomplete shipment data.

Limited logistical insights
You may experience missing or unreliable information regarding:

• Shipping status
• Transport details
• The order–shipment linkage

Update 12 March 2026

The maintenance was completed successfully within the scheduled time window. Please verify your orders and cancellations to ensure all information is correct.

Good news! On 18th of March, we will update the error message returned by the Create Shipment, Get Delivery Options and Create Shipping Label endpoints when a request contains order items that do not belong to the same order.

Old message (example)
“Request contains order item id(s) that do not belong to the same order.”

To provide clearer guidance, we have improved this message.

New message (example)
“Your request has order item id(s) that are not in the same order. Please change the request into separate request(s) with order item id(s) 2182285438, 2182285439. And with order item id 2182285440”

*Note: This message could look a bit different with more or fewer order items.

On Tuesday, March 17, between 06:00 and 07:00 CET, we will perform scheduled maintenance. During this window, order sourcing will be unavailable for approximately 10 to 30 minutes.

This means that no new orders will appear in the order endpoints during the downtime. Customers can continue placing orders as usual. Any orders placed during this period will appear immediately after the downtime ends.

As shared earlier, we are preparing an update to the Product List endpoint to ensure that the product positions returned through the API match the actual positions customers see on bol. This change will improve consistency between what partners retrieve and what shoppers experience on the platform.

This update, originally announced in our previous message, has been postponed to March 16. The rollout will take place gradually, and we expect it to be fully completed by March 30.

After the rollout of the change to the product ranking endpoint, a bug was introduced affecting the Accept-Language parameter in the header, causing only "nl" and "fr" to be returning data. This issue has now been resolved, and as of this afternoon you should be able to use all headers as described in the API specification.

Note: It is still possible that no data will be returned for some of your products. As mentioned in the announcement post, due to the definitional change and the improved method of measuring impressions, significant differences in the data are expected.

You can read more about it in the announcement post.

At the moment, we are experiencing an issue with updating and creating offers. You may receive a timeout message when trying to update or create an offer. We are investigating the cause and will post an update once we know more.

Sorry for the inconvenience.

Update February 25

The issue has been fixed since this morning. It’s possible that some stock and price updates were not processed correctly; in those cases, you would have received a timeout. Please check your stock and price values if you do not update these regularly.

On 19 February, there will be a planned maintenance window between 12:00 and 12:30 CET. During this period, it will not be possible to retrieve or process customer invoices.

Thank you for your understanding.

Update

The maintenance has been completed successfully.

Starting February 23 2026, at approximately 10:30 AM CEST, we will gradually route traffic internally within bol for the 4 endpoints under the /content resource.

Traffic will be phased in according to the schedule below:

• Feb 23 - 26, 2026: 1-20% of partners will be migrated
• Mar 2, 2026: 50% of partners will be migrated
• Mar 3, 2026: 100% of partners will be migrated

No changes are required from your end, and no impact is expected in terms of integrations or operational processes. The functional behaviour of the endpoints remains unchanged. If you notice anything out of the ordinary, please let us know through our regular support channels.

As announced on 08‑01, the /retailer/insights/product-ranks endpoint would transition to the new IAB‑aligned (Interactive Advertising Bureau) measurement standards at a later date. We can now confirm that this update will go live on 18 February 2026.

What’s Changing?

The following data point will now follow the updated measurement methodology:

• Ranks.impressions

Important: Change in Definition

To align with the new measurement system, the definition of impressions for this datapoint will change.

• Before February:
  Impressions were calculated based on renders.
• Starting February 1st and onward:
  Impressions will be calculated based on views.

This means that any data retrieved from this endpoint will reflect a new standard from the moment the update goes live.

The new measurement methodology will be retroactively applied starting 1 February 2026.
Data before February will remain measured based on renders.

Because of the definitional change from renders → views, you will notice a 50-60% shift in impression counts when comparing January and February. This is expected and reflects both the improved consistency with the new measurement system and the definitional change.

As communicated before, since 12 September 2025, the EU Data Act requires sellers of connected (smart) products to inform consumers before purchase about the data these products collect and how users can access, view, share, or delete that data. Connected items include devices such as smartwatches, robot vacuums, smart lighting, and household appliances with internet connectivity.

To comply with the law, sellers must provide information on:

• The type, format, and amount of data the product generates.
• Whether data is collected continuously or in real time.
• Where the data is stored (on the device or an external server), including retention periods.
• How users can access, request, or delete their data, including service terms and quality.

In addition to the Data Act, certain items also require energy labels and product information sheets. Bol will start actively enforcing all mandatory product information (including EU Data Act obligations) on 1 April 2026. Missing required information will result in products being taken offline in phases.

Sellers are fully responsible for compliance. Bol provides tools and explanations, but this is not legal advice. For substantive questions, sellers should consult a legal adviser.

For more details, please visit our Partnerplatform.

We would like to inform you about scheduled maintenance on 20 January, from 12:00 to 13:00.

During this time, it will not be possible to fulfill VVB and Network Direct orders, nor to receive order information for VVB, Network Direct, and LVB.

After the maintenance window, all new and existing orders will be visible again and can be handled as usual.

Update

The maintenance was completed at 12:30. All order flows are fully operational again.

We listened carefully to your feedback. Over the past months, we worked hard on an improved version of our Offer API. As of today, 19 January, Offer API v11 is generally available to all partners. You can now manage your offers more easily and work even more efficiently.

What is new in Offer API v11?
The updated API includes often-requested features that improve your processes:

• Improved feedback for offline offers
  Want to know why an offer is offline? You can now easily request this information using the new Not for sale reasons endpoint.
• More detailed feedback for missing content attributes
  If an offer is offline due to missing mandatory content, you can now retrieve a list of the missing attributes trough the Not for sale reasons endpoint.
• Support for refurbished offers
  You can create refurbished offers via the new API (if you have refurbished sales rights).
• Multi-country support
  Do you want to sell an item in both the Netherlands and Belgium? You can now do this with one offer, as long as all other offer details are the same.
• Retrieve offers via a paginated endpoint
  You can now retrieve all your offers via a paginated endpoint, instead of the offer export CSV. You can request up to 100 offers per page.
• Synchronous processing of offer data
  The process status mechanism is no longer needed. Requests to create, update, or delete offers are processed immediately.
• PATCH endpoint for offer updates
  You can now update multiple parts of an offer in one request, instead of sending multiple separate requests.
  

Switch from Offer API v10 to v11 in time
With the launch of Offer API v11, version 10 is now deprecated. On 1 February 2027, Offer API v10 will be removed completely. So you have one year to migrate to v11. But the sooner you switch, the sooner you'll benefit from the advantages.

Do you work via an intermediary or third party? Then the switch to the new version will happen automatically later this year. To be safe, check this with your technical contact.
Do you have your own API integration? Explore the complete overview of new features here, or go directly to our Offer API v11 documentation.

On January 19th at 12:00, the Offer API v11 will move out of beta and the Offer v11 version will go live. As part of this change, the required request header will be updated.

The current header (Content type- and Accept header):

application/vnd.retailer.v11-beta+json

This will change to (Content type- and Accept header):

application/vnd.retailer.v11+json

If you are currently using the v11 beta, please make sure to remove -beta from the header by January 19th at 12:00 to ensure your integration continues to work as expected.

Update

At 12:00 (Dutch time), we expect a short downtime of approximately 30 minutes. During this period, the offer v11 beta endpoints will be unavailable.

The Commission Beta Endpoint will be deprecated. This endpoint will not be Generally Available (GA) and will no longer be supported from March 1st 2026.

This beta was introduced to explore new ways of providing commission data and commission calculation flexibility. While it helped us learn, this functionality does not align well enough with our ambitions of clear endpoints, transparent commission rates and ease of use.

Our vision remains unchanged: A Commissions API that offers both endpoints to perform calculations and endpoints providing full commission rate details, including price buckets. Both in single and in bulk. This beta was not the right solution to achieve that, and will thus not be GA.

To not disrupt services to your customers, the deprecated beta endpoint will remain available for the time being. As the endpoint is deprecated, no support will be provided. We intend to remove this deprecated endpoint after providing a suitable alternative.

In case of a question, please reach out through retailerapi-beta@bol.com.

From mid-February, the Get product list endpoint will be updated to match product positions shown on bol. The exact date will be announced soon.

What’s Changing?

Currently, when a product belongs to a product family, the API response includes both the parent product and all its variants. This can cause discrepancies between the API output and the ordering shown to customers on the webshop.

Because the API returns all variants, even when they are rolled up on the webshop, subsequent products may appear shifted in position. This can lead to incorrect interpretation and decision-making based on product ranking.

New Behavior

To address this, only parent products will be included in the response. This ensures that the positions in the API output match the actual positions shown on the bol webshop.

We would like to inform you that scheduled maintenance will take place on 14 January between 08:00 and 08:15.

During this window, the orders endpoint may experience temporary downtime.

Between 05:45 and 09:15, we experienced issues affecting the orders endpoint. Our teams have been actively investigating the root cause. The issue has now been resolved, and the endpoint has been fully operational again since 09:15 this morning.

We apologise for the inconvenience and appreciate your patience.

We are currently experiencing an issue with content uploads. As a result, you may be unable to upload content or may only be able to upload it partially. Our teams are working on a solution and will share updates through this message as soon as more information becomes available.

We apologize for the inconvenience.

Update

The issue seems fixed since 15:30. We will continue monitoring to ensure stability. Thank you for your patience.

Update 08-01: For the Retailer API, please note that the following endpoint and data point do not yet reflect the new measurement standards. These will be updated to the new standard in February. The change will not be applied retroactively to data starting January 1st; it will take effect from the moment the update goes live.
The exact release date of this data point will be communicated in a separate post later this month.

Impacted endpoint and datapoint:
/retailer/insights/product-ranks

• Ranks.impressions

The e-commerce market is evolving rapidly. To keep pace, we are updating our measurement system for advertising and e-commerce data in line with IAB Europe standards. This update will deliver:

• Sharper insights
• Improved comparability with other platforms

Please note: Your results may change slightly. This update affects data in both sales accounts and advertising data.

Starting today January 6, the updated measurement system will go live. However, data will be retroactively adjusted from January 1, 2026.

For the Retailer API, The following endpoints and fields will reflect the updated measurement standards:

• /retailer/insights/offer
  • OfferInsights.total
  • OfferInsights.countries.value
  • OfferInsights.periods.total
  • OfferInsights.periods.countries.value
• /retailer/insights/search-terms
  • SearchTerms.total
  • SearchTerms.countries.value
  • SearchTerms.periods.countries.value
  • SearchTerms.relatedSearchTerms.total

For the Advertiser API, The following endpoints have been reflecting the new updated measurement standards since October:

• /advertiser/sponsored-products/reporting/performance
• /advertiser/sponsored-products/reporting/target-page
• /advertiser/sponsored-products/reporting/advertiser
• /advertiser/sponsored-products/reporting/search-term
• /advertiser/sponsored-products/reporting/category

For more details, please visit our Partnerplatform.

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 09:45

For now, it appears to be a false alert, but we are investigating further to confirm.

Update 13:00

After some investigation, we conclude that this alert can be considered a false alarm. We apologize for the inconvenience.

Following our earlier post about the launch of our Offer API v11, as of today, the beta for this new API is now open to everyone. This means you no longer need to request access.

What’s new in Offer API v11?
The new Offer API introduces several frequently requested features from our partners:

• Synchronous processing of offer data
• Paginated offers endpoint with filtering options by EAN and last modified datetime
• Updating (parts of) an offer via a PATCH endpoint
• Support for refurbished offers
• Multi-country offer support
• Improved feedback on why an offer is offline

Additionally, we also improved the not-for-sale-reasons endpoint. In case your offer is offline due to missing mandatory content (reason code 4004-2), we directly show which content attributes are missing. This makes it easier to resolve this particular reason.

Explore the full feature overview here, or go directly to our Offer API v11 documentation.

In case you already had access to this new Offer API, nothing changes. Do you have any questions or feedback? Feel free to mail us via retailerapi-beta@bol.com.

We’re excited to officially launch version 11 of our Offer API! This new version incorporates frequently requested features from our partners. Version 11 will remain in beta for approximately three months, starting with a closed beta phase running until November 24th. After this date, it will become an open beta.

What’s new in Offer API v11?
The new Offer API introduces several highly anticipated features:

• Synchronous processing of offer data
• Paginated offers endpoint with filtering options by EAN and last modified datetime
• Updating (parts of) an offer via a PATCH endpoint
• Support for refurbished offers
• Multi-country offer support
• Improved feedback on why an offer is offline

Explore the full feature overview here, or go directly to our Offer API v11 documentation.

Interested in early access?
We’re inviting a limited number of partners to join the closed beta. If you would like to join the group of early adopters, please email us at retailerapi-beta@bol.com. Spots are limited, so respond quickly if you’d like to participate!

Future updates regarding the Offer API beta will be shared via this developer portal.

Update November 24, 2025
As of today, the closed beta has officially ended, and the Offer API v11 beta is now available for everyone to use. This means you no longer need to request access.

Together, we’re constantly building a platform that works even better for everyone. That’s why we’d love to hear how you experience the bol Retailer API and Advertising API (bol API). Your feedback helps us improve important areas like functionality, documentation, and technical support.

How it works:

• The survey takes 10 minutes to complete
• Your answers are for internal use only and will not be shared
• The survey closes on December 1st 2025

> Take the survey

Thank you for taking the time to share your feedback!

Between 14:40 and 15:00, there was an issue with collecting orders, which temporarily prevented the creation of shipments. A fix has been implemented, and the system is now functioning normally again.

We apologize for the inconvenience and appreciate your patience.

This morning, between 06:00 and 08:00, we experienced an incident that impacted the processing of email data and the sending of invoices.

The issue has been resolved, and all systems are operating normally.

We apologize for the inconvenience

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 27 October 10:30

We are currently experiencing slower response times on the Retailer API, primarily affecting the offer endpoints. The issue began on Saturday, October 25th, at 06:00. We are actively investigating the root cause and working to restore normal performance.

Update 27 October 16:40

We have implemented changes to improve the processing throughput of asynchronous requests and are monitoring the results. While performance has improved, it has not yet reached the desired level. We are continuing to work on further optimizations.

Update 27 October 20:10

Between 18:50 and 19:15, the Retailer API returned an elevated rate of 503 errors. The issue was mitigated by 20:00, and the API is currently operating normally.

We will continue to monitor the situation to ensure stability. We apologize for any inconvenience this incident may have caused.

We’d like to inform you about an update to the delivery options returned via the “Get Delivery Options” endpoint.

What’s changing?

• From now on, when you announce your shipment, we’ll show only one carrier option per delivery network:
  • one for the “SameDay" network
  • and/or one for the “NextDay" network
• This means it’s no longer possible to switch between carriers within the “SameDay" or “NextDay” networks.
• You can still switch from the “SameDay” network to the “NextDay” network, and the option to switch between parcel and mailbox remains available.

With this update, we’re improving forecasting and working together towards more efficient and reliable deliveries.

Thank you for your cooperation!

We’ve updated the Get Catalog product details by EAN endpoint to include Manufacturer Details in the product attributes. This means that when retrieving product data, you may now see manufacturer-related attributes in the response. These attributes help provide more complete product information for display purposes.

What’s changing?

• The response from the Get Catalog product details by EAN endpoint now includes manufacturer-related attributes.
• Examples of attribute IDs you may encounter:
  - Manufacturer Name
  - Manufacturer Address

What you need to do:

• Ensure your integration can handle these additional attributes if needed.
• No changes are required for submitting product data — this update only affects retrieval.

As previously announced, bol is making a change to the IP address used for api.bol.com on October 15th, 2025.

• Required action (for users with an allowlist):
  Please update your allowlist to include the following IP range: 79.170.100.0/22. Failing to allowlist this range may result in blocked traffic or service disruptions once DNS changes are applied.
  
• No action required (for users without an allowlist):
  If you do not use an allowlist to connect to api.bol.com, no changes are necessary, and your integration will continue to function normally.

We are currently experiencing an issue with the retailer API. As a result, the visit, product rank, and search term data on the insights endpoints are not up to date. We are working on a solution and will update you as soon as we have more information.

Our apologies for the inconvenience.

Update:
The issue has been resolved.

A new field quantityShipped is introduced in the response body of the shipmentItems of the Get a shipment by shipment id endpoint.

• quantity refers to the amount of ordered products for this order item id.
• quantityShipped refers to the amount of shipped products for this order item id.

Why have we added this

This enhancement provides retailers and intermediaries with more clarity for the difference between the quantity ordered and actual shipped quantity quantityShipped.

You can find the updated technical documentation for this endpoint here.

The label name Ampere-Ampere will be replaced by:

• Ampère Same-day Morning – Letterbox
• Ampère Same-day Morning – Parcel

This change clarifies the type of shipment and indicates that Vvb shipments must be handed over to Ampère in the morning for same-day delivery. Please note that this change is visible in the Get Delivery Options endpoint.

We've recently become aware that partners who have newly started using 'MijnLeverbelofte' as their delivery code have experienced their offers being taken offline.

We're currently investigating a solution. In the meantime, we advise partners not to use 'MijnLeverbelofte' unless it was previously configured without causing their offers to go offline.

Update 02-09: Although the issue was previously marked as resolved, we’ve identified that it is still occurring. We are now actively investigating a new solution that will fully address the problem. Please note that this issue only affects partners who joined our platform around July 31st.

Bol is making a change to the IP address used for api.bol.com, starting October 15th, 2025.

• Required action (for users with an allowlist): 
  Please update your allowlist to include the following IP range: 79.170.100.0/22. Failing to allowlist this range may result in blocked traffic or service disruptions once DNS changes are applied.
  
  No action required (for users without an allowlist): 
  If you do not use an allowlist to connect to api.bol.com, no changes are necessary, and your integration will continue to function normally.

At the moment, we are experiencing an issue with content uploads. After submitting a content upload request, you can check the status of the request via the "Get an upload report by upload ID" endpoint. Due to an issue this endpoint currently returns the status "In progress".

When checking the process status response of the request, you may receive a success message. We are currently investigating the root cause of this issue.

Update 28-08, 14:30
A fix has been implemented, which has resolved most cases. However, for a limited number of older upload reports, the report status may still incorrectly show as "In progress", even though all individual attributes within the report have reached a final status (either "published" or "declined").

To ensure accuracy, we recommend re-uploading the content if the report status remains "In progress". The new upload report will correctly reflect the status.

We apologize for the inconvenience.

We will be carrying out maintenance on the 26th of August between 06:45 and 07:30. This maintenance will have impact on the following flows:

• Retrieving orders
• Shipping orders
• Retrieving delivery options
• Creating shipping labels

We are currently investigating an issue where shipping labels sometimes may remain stuck in a 'PENDING' state, eventually resulting in a 'TIMEOUT' error.

Our team is actively working on identifying the root cause and implementing a solution.

As mentioned in this article, on August 12 2025, bol changed the format of shipmentId and transportId in the API. This update affects the shipment endpoints and the entityId in processStatus responses.

Please ensure that your integration has been updated to handle the new format.

Last week, we launched two new offer subscriptions to our Subscriptions API to get to know when your offers becomes online or offline: the OFFER_FOR_SALE and OFFER_NOT_FOR_SALE event.
The OFFER_NOT_FOR_SALE event can be used to know immediately when your offers goes offline. By using this event you can respond quicker to an offer change. Similarly, the OFFER_FOR_SALE event will let you know once your offer becomes online on the bol marketplace.

If you are creating offers via the Retailer API v10, and you want to know when your offer has been processed completely on the bol marketplace, you can subscribe to both events. In that way, you will always know when the processing done.

You can find more information on our API documentation.

From September 2nd 2025 onwards we are improving the logic of price stars for Logistics via bol items under €25.

What do these changes include?

• For items under €25, the €2.99 shipping costs are no longer added in the price star calculation.
• This means these items can now earn better price stars, making Logistics via bol even more appealing for items under €25. Use this opportunity to help partners expand their Logistics via bol assortment.
• Please note: this change only affects price stars. It won’t affect your chances of getting the buy box for your Logistics via bol offer.

There will be no changes to the API, only to the Lvb price star logic for offers <€25. Price star information can be retrieved via the dedicated endpoint. Where applicable, make sure to adjust relevant Lvb price star logic to accommodate these changes.

Merchants will see the price stars in your sales account under 'My Items'. You can find more information about price stars here. Have you received any questions? Contact API support or your partnership manager.

As mentioned in this article, starting August 12, 2025, bol will change the format of shipmentId and transportId in the API. This affects shipment endpoints and the entityId in processStatus responses.

If needed, please update your integration to handle the new format before the deadline.

Between ~19:10 and 21:25 on Sunday, 27th July there were issues related to the creation of shipping labels, shipments.

The issue is resolved since 21:25 - it is possible again to create shipments, shipping labels.

We apologize for the inconvenience.

Starting 12 September 2025, the European Data Act (Data Act) will come into effect. This European regulation requires partners to inform consumers in advance about the data collected by connected items — such as smart devices. On the following Partnerplatform page you can read more about the Data Act and what it means for you as a partner.

From September 12, partners who sell connected devices will be required to inform customers before purchase about what data the device collects and how they can view and share that data themselves. To help you with this, we have created this template. Using this template isn’t mandatory, but it can help you meet the requirements quickly and easily. You are also welcome to upload a document from the manufacturer, as long as it includes all the required information.

How can I upload the information?

Via the seller dashboard
Bol will make it possible to upload this information as a document via the seller dashboard starting 12 August 2025. You can use the template or have the manufacturer provide their own document.

Via the Retailer API
From 12 August, you can also upload the document via the Retailer API (either the template or a manufactures document):

• Use the ‘Create content for a product’ endpoint
• Add the document as an asset, similar to adding a manual, CE marking, or energy label.

For technical details, refer to the API documentation on adding assets via the API.

Enforcement from 12 September 2025
The Netherlands Authority for Consumers and Markets (ACM) will monitor compliance with the law. You are responsible for complying with the Data Act. We support you with tools and information, but this text does not constitute legal advice.

Support
For help with uploading the document via the Retailer API or seller dashboard, you can contact Partner Service. For legal questions, please consult a legal advisor, as this concerns legislation from the European Union.

A change deployed yesterday to our Invoicing service caused timeouts when uploading customer invoices via the Retailer API. As a result, several invoices were received but have not yet been processed.

We are actively processing the affected invoices manually. No action is needed on your end, but you may notice some delays until the backlog is cleared.

We apologize for the inconvenience.

Update July 22
As of this morning, the issue has been resolved. All affected invoices have been successfully processed.

A new optional parameter ‘vvb-only’ is available in the Get a list of orders endpoint since July 11.

What’s new

• The vvb-only parameter allows you to filter the response to include only new or changed Vvb (Verzenden via bol) orders.
• When vvb-only=true, the response exclusively returns Vvb orders that are new or have changed.
• When vvb-only=false or the parameter is not set, the endpoint returns all orders, as before.

Why this new parameter?
This parameter enables API users to retrieve only relevant order updates that involve Vvb orders.

What does this mean for you?
There are no breaking changes introduced with this update. Existing integrations will continue to work as before. This is an optional enhancement designed to improve filtering capabilities and usability.

For more technical details, visit the updated API documentation.

We would like to inform you about a scheduled system upgrade taking place on Thursday, July 3rd at 10:00 AM.
Due to this update, there may be a brief (a few seconds) period of downtime.

This may temporarily impact order shipments and cancellations.

This coming Thursday, it will not be possible to process orders between 7:00 AM and 7:15 AM. This is due to an update we will be performing at that time.

Sorry for the inconvenience.

What’s changing?
Starting July 14, if multiple active account budgets have the same end date, we will no longer select the highest remaining amount. Instead, the system will select the oldest budget. This change ensures more efficient use of older budgets and simplifies our billing processes.

Example
Imagine you have the following active budgets on 1 June, all ending on 30 June:

Budget A
Einddatum 30 juni
Aanmaakdatum 1 maart
Resterend bedrag €100

Budget B
Einddatum 30 juni
Aanmaakdatum 15 april
Resterend bedrag €500

Old situation: We picked the one with the most money left (budget B), meaning older budget A might go unused.

New situation: Now we pick the oldest (budget A), so older budgets don’t get left behind.

What does this mean for you?

• This logic will be applied automatically in the background - no action is required on your part for standard use cases.
• If your implementation relies on or overrides budget behavior, you may wish to review your setup.
• Want to prevent an old budget from being used? Simply assign a clear end date.

We recommend sharing this update with your technical team to ensure a smooth transition.If you have any questions or concerns, don’t hesitate to reach out..

On August 12th, we will update the shipment ID format. This change will affect the following shipment endpoints and the entityId field in the processStatus response for create shipment requests.

This change should not significantly impact your implementation, as the field type remains a string, although the string will be formatted as a UUID. However, please ensure that your handling of the shipmentId is correct to accommodate this change.

Example of the current format (string):
- "shipmentId": "987654321"
Example of the new format (UUID string):
- "shipmentId": "3f7c9be4-0cd7-4bde-97f7-f611a0cf27c5"

Update 04-06-2025

On August 12th, we will update the transport ID format. It will still be a string, but now structured as a UUID. Please note that after this change, you may still receive the old format for some existing orders. This won't be an issue as long as your system accepts strings.

Our sponsored products search algorithm has been updated as of 14 May. This may affect your ad positions.

From 14 May, we are updating the search algorithm for sponsored products. This may affect your campaigns. Monitor your performance closely in the first weeks and adjust your bids or strategy as needed based on results.

What does this mean for my campaigns?
This update may have little to no effect on your campaigns. If impressions, clicks or cost-per-click (CPC) remain stable and your campaigns perform as expected, no changes are needed. If you do see changes, consider adjusting your campaign setup or daily budgets.

Learn how to analyse your campaigns and find tips to improve your campaign KPIs here.

Growing Smarter Together.

We had an issue with creating shipping labels. Due to this issue, it was not possible to create shipping labels from 09:45 to 11:00.

Sorry for the inconvenience.

We experienced an issue with the shipment labels endpoint, which made it impossible to create labels between 14:00 and 15:45. The problem has now been resolved, and label creation should be functioning normally again.

sorry for the inconvenience.

We are currently experiencing an issue with the upload invoice endpoint, which causes requests to remain in a pending state. Our team is working on a solution.

Sorry for the inconvenience.

Update 15:15

The issue is resolved since 14:30

We are currently experiencing an issue with the Get Invoices endpoint. Attempts to use this endpoint result in a 500 error.

Our team is actively working on a fix. We apologize for the inconvenience.

Update 14:50

The issue has been resolved since 14:30. Apologies for the inconvenience.

Due to scheduled maintenance on Tuesday between 12:00 and 12:30, some functionalities will be temporarily unavailable:

• Orders (VVB & Plazadirect) will not appear in your “verkoopaccount” or be received via the retailer API
• Cancellation requests initiated by retailers will not be processed
• Shipping label requests via the API will be unsuccessful

Because of this maintenance, it will not be possible to process VVB and Plazadirect orders.

Since 16:26, we have been experiencing an incident. Users may encounter intermittent 4xx errors.

We are working on identifying the issue. As soon as we know more, we will update this message. Sorry for the inconvenience.

Update 18:38

The issue has been resolved since 18:30. Apologies for the inconvenience.

At the moment, we are experiencing an incident. Users may encounter intermittent 401 errors.

Update 14:40
The issue has been resolved since 14:30. Apologies for the inconvenience.

Currently, we are experiencing an issue with the Get Lvb Inventory endpoint. Some users are reporting that the BSKU and EAN number for a product are identical. Additionally, stock information appears to be incorrect at times.

Update 12-03-2025
We're still facing some issues aggregating stock with the same EAN correctly, which sometimes results in two lines with the same EAN. We're working on a fix. Sorry for the inconvenience.

Update 14-03-2025
At the moment, we are still trying to fix this issue. We are doing our utmost to resolve the situation as soon as possible.

Update 17-03-2025
The issue was resolved on March 17 at 14:30. Since then, the data has been returned in the same format as prior to the issue.

The Share of Voice (SOV) report gives advertisers insights into their share of total Sponsored Products impressions and clicks for their brands and categories. It enables comparisons within specific chunks, page types, channels, and countries, showing how a brand’s share stacks up against competitors in each segment.

For example, if Chunk X receives 100,000 impressions in January and Advertiser Y generates 10,000 impressions for their brand(s), their impression share is 10%, while the remaining 90% belongs to other advertisers. These insights help advertisers evaluate whether increasing ad investment could boost their brand’s presence within a segment.

The report also provides granular breakdowns—such as the impression share in the "Babyverzorging" category on search pages via desktop for the selected brands—helping advertisers optimize their budgets by focusing on specific categories, page types, or devices.

Note: The SOV report only includes data for brands and categories that an advertiser is actively promoting with Sponsored Products. It does not provide insights into unadvertised brands and categories.

For more information see Bulk Performance Report Examples and Bulk Performance Reports documentation.

Due to this morning's CodeFlow downtime, some users are experiencing authentication issues. We are investigating the problem and will update this message as soon as we have more information.

Update 04-03, 11:15
The issue is resolved. Sorry for the inconvenience.

Update 04-03, 20:45
This afternoon we received reports from some intermediaries that some users were unable to fully complete the OAuth flow. The IT team implemented a fix around 19:25, which resolved most cases. However, there are still a few instances where the flow fails, mainly related to an issue with double encoding of the state parameter. The IT team will continue investigating this tomorrow morning to find a resolution on our side.

As a quick fix to the issue with double encoding of the state parameter, regardless of the changes on our side, we recommend switching to URL-safe base64 encoding. Switching to URL-safe base64 encoding should provide the fastest and most reliable fix in the meantime. More details on the difference between base64 and base64 URL encoding can be found in this article.

Update 05-03, 15:30

The issue has been resolved for all users. Sorry for the inconvenience.

The change regarding the SSO/CodeFlow application that was rolled back last week will be re-implemented. The planned maintenance is scheduled for Tuesday, March 4, from 5:00 AM to 5:30 AM.

During this timeframe, there will be temporary downtime for the SSO application. Authentication via Codeflow/SSO will not be possible during this window.

Due to this morning's CodeFlow downtime, some users are experiencing authentication issues. We are investigating the problem and will update this message as soon as we have more information.

Update 26-02, 11:15
Due to a failed deployment this morning, we did a rollback. The CodeFlow service should work again for all users.

The new PDP Performance Report in the Advertising API allows advertisers to download daily PDP performance metrics in CSV format for analysis. It introduces exclusive metrics like Impression Share, Click Share, Total Impressions and Total Clicks, providing deeper insights into Sponsored Products on Product Pages.

For manual campaigns, data is now grouped by CategoryId, enabling better bid optimization, while for automatic campaigns, the deepest aggregation level is adGroupId. Advertisers can use this report to track key metrics (e.g., impressions, clicks, conversions, ACoS, ROAS), optimize bidding strategies, and improve campaign performance.

For more information see Bulk Performance Reports and Bulk Performance Report Examples functional documentation.

Based on your feedback, we now show two contraints on the Ad giving more information on why the ad is currently not running/being served:

• BLOCKLISTED - The product in question is not allowed for advertising due to regulatory restrictions.
• NOT_BEST_OFFER - The product do not have the Buy Box.

For more information see Retrieving ads functional documentation.

In accordance with the Digital Services Act, bol has improved the processes of indicating to the consumer who the responsible economic operator in the EU is.

Via the new Economic Operators resource, partners can now create and manage their own economic operators. These economic operators can then be linked to a partner's offer. The existing offer endpoints have been updated to include the economicOperatorId as an optional attribute. This gives partners full autonomy to manage their own data. Economic operators are specific to each partner and are not shared between them.

The economic operator fields in the content data model have been removed. What was previously uploaded will remain visible in the webshop until February 1st 2025. Afterwards, they will be deleted.

The management of economic operators and linking them to offers is possible through the Retailer API and through the bol seller dashboard.

Since 18:00 on January 31, 2025, we have been experiencing issues with the Pub/Sub webhooks. This affects competing offers, so your repricer may not work.

Update: 17:30 The issue is resolved. Sorry for the inconvenience.

A nice practical improvement to two sponsored products reports based on your feedback!

• The Campaign level bulk report now includes campaignName column alongside the existing campaignId, making it easier to read and organize.
• In the Bidding bulk report, you’ll now see an adGroupId column next to adGroupName, providing more detailed insights.

These changes improve the readability and usability of the reports, making it a bit easier and more user-friendly to analyze your performance data.

For more information see the Campaign Level and Bidding Report functional documentation.

Since 11:15 on January 22, 2025, we have been experiencing issues with the create shipping label endpoint and get delivery options endpoint. It is also not possible to download vvb labels via 'verkoopaccount'.

We are investigating this with emergency priority.

Update: The issue was resolved at 12:00. Sorry for the inconvenience.

Since 16:50 on January 21, 2025, we have been experiencing issues with the Get Orders Order-ID endpoint and Commissions endpoint.

We are investigating this with emergency priority.

Update: The issue was resolved at 18:30. Sorry for the inconvenience.

On January 22, the offer resource will have downtime between 6:00 AM and 6:20 AM. During this time, it will temporarily not be possible to use all the offer endpoints.

Since 10:00 on January 15, 2025, we have been experiencing issues with connecting to our retailer API via CodeFlow (OAuth).

We are investigating this as a priority emergency incident.

Update: At the moment, we are still working on resolving this issue. If you encounter this issue, you will receive a 403 response from the retailer API.

Update 17:25: We have identified the root cause of the issue and are working on resolving this as fast as possible.

Update 18:54: We have released a possible fix. Please verify if this solved the problem. If not please let us know.

Update 19:33: The fix worked for the token endpoint, but did not yet fix the 403 errors. Still trying to fix that.

Update 21:30: New fix is live. Please let us know if you still have problems.

Update 23:30: The fix seems to have recovered most of our API traffic, although some retailers still report problems (especially for retailers using GoedGepickt, Picqer, ChannelAdvisor/ Rithum). Our hypothesis is that re-authenticating bol solves those problems.

Update 16th Jan 15:05: We deployed a last small fix, which should fix any remaining problem. Especially for GoedGepickt, Picqer and Rithum partners. Please contact your intermediary in case it doesn't work yet.

We apologize for the inconvenience.

On December 18th, from 6 am to 8 am, there will be planned downtime for the Invoices endpoints due to maintenance. During downtime, the following endpoints will not be available:

• Get all invoices
• Get an invoice by invoice id
• Get an invoice specification by invoice id

On December 6th, 2024, we introduced new behavior that made the Update an offer endpoint work more consistently as a PUT endpoint, by making sure that an empty economicOperatorId value as well as a null value would clear the economic operator data from an offer. This change has had an unfortunate side effect, where economic operator data has been unintentionally removed from an offer when no economic operator value was sent in a call.

New situation
On December 13th, 13:30 we implemented a new change where an omitted value no longer removes an economic operator. As of December 13th, there are now three options regarding the economicOperatorId field:

1. To set an economic operator
   a. {"economicOperatorId": "some-uuid"}
2. To keep the existing economic operator
   a. {"economicOperator": null}
   b. {}
3. To unset (remove) an economic operator
   a. {"economicOperatorId": ""}

See the release notes for more information.

We apologize for any inconvenience caused. If you have any questions or comments regarding the change, please get in touch with Partnerservice or your contact person within bol.

Since 15:50 retrieving new orders is delayed. Investigation has started

Update 17:32

Issue seems to be fixed, still monitoring.

Update 08:36

Since yesterday 19:05 there are issues with retrieving new orders and shipping orders via the Retailer API. This is being investigated with emergency priority.

Update 10:21

Unfortunately the incident is quiet complicated.

Shipping orders via API is actually possible, just the feedback of the shipment is impossible to retrieve from us.

Current known impact:

- Retrieving new orders since yesterday 19:05 impossible

- Shipping orders does not receive feedback since yesterday 19:05

- List of shipments in API and SDD show shipmentid/transportid 0

Where possible the SDD could be used to retrieving/shipping your new orders.

Update 12:08

We are currently rolling out a fix for retrieving new orders, this seems to be working.

Orders from 19:00 until now are still stuck and can't be retrieved yet. We are trying to fix that too as soon as possible

Update 13:36

Still working on a fix for the stuck orders.

Side effect of this issue is that cancellation requests are currently being received before the order is received. This results in inaccurate feedback. For example that the order item is already cancelled.

We apologize sincerely for the impact that this issue has on your operations on a Monday morning during the peak season.

Our main focus is to solve the issue as soon as possible. After that, we will communicate how we will prevent impact on service norms for delayed orders.

Update 15:15

We are very close to a solution

Customers are informed that orders are delayed when pick-up is missed (VVB) or on the day of delivery (non-VVB)

Update 15:43

The solution has been rolled out. Everything should work as expected.

Please carefully check all open orders on all pages. Orders placed yesterday potentially landed on later pages.

In case you cancelled any orders on request of the customer the past hours, please check if that was processed successfully.

An update on how we will prevent impact on service norms will follow.

Together with you, we’re constantly improving our platform. That’s why it’s very important to us to know how you feel about the Retailer / Advertising API. Your feedback helps us improve specific matters, like technical documentation, API resources, and technical support. We look forward to hearing your ideas!

You can access the survey by clicking on the button below. The survey takes approximately 10 minutes of your time and can be completed until December 2, 2024. Your response will be anonymous.

> Fill out the questionnaire

If you are not responsible for the integration of the API, please feel free to forward the survey link to your colleague who is responsible for the API integration.

Thank you in advance for your time and feedback!

The data from 26-11 is currently missing in the search term data.

The data from 25-11 is filled since 26-11 18:00

At the moment, we are experiencing an issue with our subscription endpoints. As a result, it is currently not possible to use subscriptions for PROCESS_STATUS and SHIPMENT.

We will update this post as soon as we have more information.

Update: The issue was resolved at 3:00 PM.

This morning, between 11:00 and 11:40, we experienced an issue with sourcing orders. This affected both fulfillment by bol and fulfillment by retailer orders.

The issue has now been resolved, and all orders in the queue will be sourced.

On 12 November 2024, an incident took place, which impacted a large part of our API landscape. We are aware of the impact these outages can have on our partners. Especially as you were preparing for a successful season. Also, this specific incident lasted longer than you may expect from us. To show our commitment on making sure this does not happen again, we would like to share our actions taken last week.

Increasing resilience for high load

This specific incident was triggered by an unexpected peak in the load on the Retailer API. We have scaled up our capacity to make sure these spikes can be handled in the future. Similar peaks have been handled successfully since.

Identifying the source of these peaks

We are identifying the source of the peaks in traffic, so we can come up with solutions that may prevent these kinds of peaks.

Improve nighttime monitoring and alerting

As the incident was only solved in the morning, we have reviewed our monitoring and alerting to better cover these nighttime incidents.

With these measures in place, we are committed to working with you to run a successful season without major unforeseen events to our API's.

We’re excited to announce the addition of TACOS (Total Advertising Cost of Sale) at the advertiser level in our API. TACOS provides a comprehensive view of your advertising performance by calculating the percentage of total revenue—combining both ad-attributed and organic sales—spent on advertising. This metric allows advertisers to evaluate how their campaigns contribute to overall business growth, offering a more strategic perspective beyond traditional ad metrics like ACOS. Please note, this new functionality is exclusive to retailers and is not available for suppliers.

This empowers advertisers to track long-term performance trends, understand the interplay between paid and organic sales, and make data-driven decisions for scaling or reallocating budgets. Start leveraging TACOS today to unlock deeper insights into your advertising impact—tailored specifically for retailers!

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 21-11-2024 10:25

The incident was prevented yesterday and had no impact

Our data model will be changed as of the 3rd of December.

Please find more info here: English and Dutch

Large API incident since 00:30 is under investigation with emergency priority. This concerns all API activity

We apologize for the inconvenience and hope to come to a solution as soon as possible.

Update 10:40

Since 09:20 the traffic has been recovered. We are closely monitoring

Update 12:55

For clarity: The API-requests sent to use between 00:30 and 09:20 have not reached us, so they were not processed.

This API outage may impact meeting our service standards, but don’t worry, we are taking this into account to prevent unjustified strikes.

• Was your inventory out of date because of the malfunction and therefore an order cannot be processed? If so, please contact Partnerservice via the chat function in your seller account to have this order cancelled. Preferably do not cancel these orders yourself, or let such an order automatically expire after 3 days.
• We take into account partners who missed the pickup appointment for Shipping via bol due to the API outage.

As previously announced, older Retailer API versions have been removed. Currently, only Retailer API v10 is supported.

If you want to continue using the Retailer API and have not yet migrated to v10, it is important to migrate as soon as possible. To help you migrate, the migration guides below have been created:

• Migration guide Retailer API v8 to v10
• Migration guide Retailer API v9 to v10

If you have any questions about migrating to v10, please get in touch with us at retailer-api-migration@bol.com.

As previously announced, we have worked on a new way to release new Retailer API functionalities and to phase out old functionalities. This new 'versioning strategy' means you only have to update your API integration if something actually has changed.

Retailer API v10, released on October 1, 2023, was the start of this new versioning strategy. The new strategy has the great advantage that you do not have to make any adjustments to your integration in the future if nothing changes for you. In addition, we can now release new functionality more often than before.

Instead of introducing a new version for the entire Retailer API every six months, the versioning will now take place at a lower level: on resource level. This makes maintaining your API integration easier. For example, the resource 'Orders' could remain at v10, while 'Offers' moves to v11.

A resource only moves to a new version when:

• There is a breaking change on an endpoint within a resource
• An endpoint within a resource is removed completely

The old version of the resource will then be supported for at least another year.

Deadline migration to Retailer API v10

As announced, from November 1, 2024, we will only support Retailer API v10. Older Retailer API versions will be permanently removed on this date. If you want to continue using the Retailer API, please migrate to v10 before this date.

To help you migrate to v10, the migration guides below have been created:

• Migration guide Retailer API v7 to v8
• Migration guide Retailer API v8 to v9
• Migration guide Retailer API v9 to v10

If you have any questions about the migration to v10, you can contact us at retailer-api-migration@bol.com.

Note that the final day to retrieve performance data from the Advertising API connected to Mabaya (V9 and V10 Beta) will be on 27th of November 2024.

Please make sure that any data you require from our old environment is retrieved before this date.

What does this mean?

• API Calls: After the deprecation date, all Advertising API endpoints connected to the old environment will be removed and any requests made will fail.
• New API Version: The new Advertising API has received great positive feedback, and we are committed to continuing to improve it.

To see what else is coming, don’t forget to take a look at our roadmap.

We have an issue that makes it impossible to retrieve an (unpublished) offer export file. A 504 or 400 error may occur.

We are currently working on a solution. Our apologies for the inconvenience.

Resolved at 13.26 25-10-2024

We’re happy to announce the addition of the EAN (European Article Number) field to Ad Performance Bulk Report API. This enhancement helps reduce the number of API calls to retrieve performance data for an Ad. With this new EAN field, advertisers can now directly link performance data to specific products, simplifying data analysis and reporting. It allows for more efficient tracking of product-level performance.

For more informationsee the Ad Level functional documentation.

At the moment, it is not possible to use a process status, so you cannot use the POST/PUT/DELETE endpoints on our API's. We will keep you updated about this issue.

Update 19:39 This incident is still being investigated with emergency priority. The issue is with our cloud platform, but the exact impact is still not clear

Update 20:02 There is a large chance that POST/PUT/DELETE requests have to be resent once the incident is solved.

Update 21:43 Incident is still going on. Next update on this post will be tomorrow morning 8AM. Meanwhile a team is working on the incident.

Update 17/10 07:28 Between yesterday 11:30 AM and 00:15 AM tonight we had issues in the cloud. All asynchronous requests sent to us during that timeframe have to be checked for their process status. If this was not SUCCESS, it has to be sent again.

Most of the impacted requests were offer CREATE/UPDATE/DELETE.

We apologize for the inconvenience

Since release of our new economic operator endpoints, we are having some problems leading to unexpected 50x errors. We are investigating

Update 15:20 The problem was related to the code flow authentication. This has now been fixed

We just had problems with the process status endpoint. This is probably related to a deployment. We will revert the changes and investigate the problem.

It should be working soon again

Update 11:12 Things should work again. Please let us know when you still experience problems. Apologies for the inconvenience

We are experiencing an issue with the "get search terms" endpoint, which has caused yesterday's data to be outdated. Our team is currently investigating the problem and will provide an update once the issue is resolved.

Resolved at 12:00 on 02-10-2024.

We had an issue with the performance report endpoint. Because of this error, the entity-id filter was not working for keyword, target_category, and target_product entity types.

The issue started on 23-09 at 17:00, and the fix was implemented on 24-09 15:08.

Note that the final day to retrieve performance data from the Advertising API connected to Mabaya (V9 and V10 Beta) will be on 27th of November 2024.

Please make sure that any data you require from our old environment is retrieved before this date.

What does this mean?

• API Calls: After the deprecation date, all Advertising API endpoints connected to the old environment will be removed and any requests made will fail.
• New API Version: The new Advertising API has received great positive feedback, and we are committed to continuing to improve it.

To see what else is coming, don’t forget to take a look at our roadmap.

We are currently experiencing an issue with the search term data, as yesterday's data is missing. We will keep you updated on the resolution of this matter.

Resolved at 12:45.

We are launching a new way to interact with our product information data model.

The data model is now available in English for reference. This removes the need of first translating the data model prior to translating your content.

This means that all chunk names, attribute names, descriptions, filling instructions, values and units will be in English to help you understand what content is required to publish a product for a specific chunk.

This does not mean that bol supports English content.

You are still required to provide Dutch or French content.

What it does enable you to do is to make it easier for your non-Dutch/French speaking users to map and upload their product information to bol.

Bol sponsored products introduces a new functionality. Within your manual campaign you now have the ability to choose which product pages in your chosen categories to advertise on. This is a significant improvement over our previous functionality, where you could only indicate if you wanted to advertise on the 'product pages as a whole'.

For more information on how Category targeting works, please see our Partner Platform Page.

For more information on the API please see Target Products -> Expression API.

On Wednesday, August 7, there will be maintenance on an order service from 3:00 AM to 6:00 AM. During maintenance, retrieving orders, shipping orders, and retrieving shipping labels will not be possible.

Please check the process status of your requests. If requests have failed during maintenance, please resend the requests after the maintenance window.

Wednesday the 7th of August we will have maintenance on our Returns endpoints. Returns endpoints will be down from 06:30 AM to 06:40 AM.

Please check the process status of your return requests. If requests have failed during downtime, please resend the requests after the downtime.

The Advertising API now includes updated entity-metrics. All performance reports now provide metrics for both direct and indirect conversions over a 14-day period. This enhancement allows for more comprehensive tracking and analysis of your campaign effectiveness. These metrics are useful for understanding the full impact of your ads, including conversions that occur indirectly after the initial interaction. Understand which ads drive quick actions and which contribute to a customer’s decision over time. For more information have a look at: Performance Reports & Bulk Performance Reports.

Take advantage of these new insights to optimize your advertising strategies and improve ROI, ensuring better decision-making and enhanced campaign performance.

Incomplete data coming from search results pages and category pages (not from the product detail pages) was shown in the API reports and dashboards in the new sponsored products environment, over the period from July 19 to 23. It only affected the reporting data for impressions, clicks, CTR, conversions and attributed sales. Ad billing was not affected. We apologize for the inconvenience. The problem has been fixed and reports and dashboard show the correct data again.

We recommend that you re-retrieve all performance data for above dates V11 Advertising API.

Status: Solved

There will be downtime for the price star boundaries endpoint on July 22th between 16:30 and 17:30. During this period, it will not be possible to use this endpoint.

We apologize for the late notice and any inconvenience caused.

Yesterday evening between 21:00 and 23:30 we had an issue with retrieving order information. We are investigating what happened and how to prevent this from happening in the future. For clarity; for such an important process we have 24/7 support, so we are also investigating what went wrong there.

Update 17th of July 13:21We identified the root cause yesterday and measures are being taken to prevent such downtime in the future.

There will be downtime for the Invoices endpoint on July 18th between 12 AM and 3 AM. During this period, it will not be possible to use this endpoint.

We apologize for the late notice and any inconvenience caused.

Some orders have problems to be shipped. We are fixing the issue right now and investigating the root cause.

Update 11:29 The issue seems to be fixed.

• Please retry your request to ship the order.
• Please check your open orders without the parameter change-interval-minute to check if you missed changes in orders
• For VVB orders: It could be possible that you have to re-start the label process. So retrieve delivery options, and purchase a new label. This only applies to some orders. An extra label will not be charged

Apologies for the inconvenience

Web data of 6th and 7th of July missing. This impacts offer insights endpoints (with clickdata) and ranking/list endpoints. We are working on a fix and will backfill the data

Update 10-7

The issue is fixed and the data has been corrected

Our new Product Categories endpoint offers the full hierarchical product category tree of the bol webshop, helping you identify all categories and sub-categories where products can be shown. This update is also available for Advertisers.

Key Features:

• Overview: Retrieve the complete hierarchical product category tree.
• Create your own insights: Use the categories as inputs for the Product List filters and Product List endpoints.
• Enhanced Reporting: Match category IDs from advertisers' performance reports to the corresponding category names.

We are excited to announce the launch of two new reports within our Advertising API: the Attribution Report and the Bidding Report. These additions are designed to provide deeper insights and more comprehensive analyses of your advertising campaigns, empowering you to make more informed decisions and optimize your strategies effectively.

Attribution & Bidding Reports

The Attribution Report provides crucial insights into conversion pathways, distinguishing between organic and sponsored conversions, and analyzing overall revenue generation. Use this data to refine targeting, adjust bids, and allocate budget effectively across channels.

Simultaneously, the Bidding Report offers insights into auction participation, win rates, and ad performance metrics like CTR and ACoS. By integrating insights from both reports, you can refine bidding strategies based on actual conversion data and attribution insights, ensuring your campaigns are not only driving traffic but also delivering tangible business outcomes and maximizing ROI.

To start leveraging these reports, please refer to our API documentation for implementation details.

We look forward to seeing how these new capabilities will enhance your campaign strategies and drive your business forward.

To see what else is coming, don’t forget to take a look at our roadmap.

Currently, we are investigating an issue with the generation of offer exports.

Update 14-06, 17:06
The endpoint seems to be partially functioning. The investigation will be continued on Monday. Please retry if it fails for now. Apologies for the inconvenience.

Update 17-06, 10:15
Currently, the Offer export and Unpublished offers export endpoints are not working. We are investigating the issue with high priority.

Update 17-06
Since 11:50 the issue is resolved. The Offer export and Unpublished offers export endpoints are working again.

We are currently investigating an incident related to the Retailer and advertising API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 09:26
Yesterday evening, we had an outage until this morning. We are diligently working towards a solution. We will keep you updated and apologize for the inconvenience.

Update 10:24

API has been stable since ~09:00. We are monitoring the stability closely. Please resend your requests, almost no updates were processed between midnight and 09:00

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 09:29 It seems our loadbalancer has not been working between ~ 00:00 and 6:30 resulting in hardly any requests received and processed by our Retailer and Advertising API.

We are investigating and apologize for the inconvenience.

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 9:22 The Retailer API was very unstable last night and had downtime several times between 00:30 and 08:30. It should be running stable since then. We are investigating to prevent this behavior in the future.

Apologies for the inconvenience.

Unfortunately, several orders were stuck last Friday to Monday. These orders come through with a delay. You can process the orders in the usual way. We will of course prevent strikes from being given due to this malfunction.

Possible consequences:

• Orders sent via bol (Vvb) may end up in 'FBR'.
• The customer may have ordered twice.
• The customer no longer needs the item.

Do you see duplicate orders? Then it is wise to ask the customer whether they need more than one, or whether the double order was a result of the malfunction. Please note: an order will expire 3 working days after the final delivery date.

See also the following Partnerplatform page in Dutch about the issue. We apologize for the inconvenience.

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 3 June 11:23 Yesterday around 18:15 we suffered some instability on the Retailer API. This is related to last weeks nightly incident. We are still experimenting to find a definitive solution for this instability.

Apologies for the inconvenience

On June 6th, between 4 AM and 6 AM, we will have downtime for login.bol.com.

This means that during this timeframe, requests for access tokens can fail and access to the Retailer/Advertising API is limited.

Apologies for the inconvenience.

Due to a new way of measuring product visits, there will be a change in your product visits and conversion data as of May 27.

We will soon measure product visits in a different way. The new way is more precise because we recognize and filter out bot traffic better. We can therefore better identify whether a visitor to bol is a human or an automatic bot. This makes the data more reliable. Due to the new method, your product visits may be slightly higher or lower than you are used to, which also affects your conversion.

As of May 27, the change will be implemented in:

• The Get offer insights endpoint of the Retailer API
• The ‘Verkoopanalyse’ tab in the seller dashboard

Historical data will also be adjusted. From May 27, historical data can be requested up to 01-01-2023. We are currently examining whether historical data can be made available up to two years ago. As soon as more is known, we will post an update on this page.

We're excited to announce a brand new section of the Advertising API: Insights! We will be starting off with a Average winning bid for Search terms & Categories endpoint. These insights can guide advertisers in setting optimal starting bids for search terms & categories. For more information read the functional documentation or redoc technical documentation.

To see what else is coming, don’t forget to take a look at our roadmap.

Some orders cannot be retrieved in the GET single order endpoint, while they can be retrieved in the list endpoint. We are investigating this issue. As a possible workaround, the orders can be retrieved and shipped in the Seller Dashboard

Update 16:30 The issue has been fixed. Apologies for the inconvenience

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update 12:06 This morning around 6:18AM we had 5 minutes downtime. The situation was resolved

The change that was announced last friday in this post has temporarily been reverted, since 16:22 yesterday. The impact was higher than expected.

The impact will be investigated, the intention is to re-introduce the change.

The limit we want to introduce is on the number of labels that can be generated per order item. The limit will be the total quantity of the items that are being shipped.

For example:

- for qty 1 of item X -> 1 label can be generated

- for qty 3 of item X -> 3 labels can be generated

A limit to the amount of labels you can request for an item has been introduced. This is equal to the total quantity for the item, so for example if a customer ordered 7 chairs, you can generate maximum 7 labels.

For clarity, this applies to step 2 in this process.

Tomorrow morning between 6 AM and 6:30 AM, it will not be possible to process orders.

Apologies for the short notice.

We highly recommend (re)checking your code and upgrading to our Retailer API v10 before May 1st. This enables you to benefit from our new versioning strategy as well. More information can be found here.

In case of questions, please contact us at retailer-api-migratie@bol.com

To prevent new issues, we have to restart a database tonight around 4 AM. This will last until 6 AM at the latest.

Apologies for the inconvenience.

Again we are looking into a lot of time-outs for our offer endpoints. This is caused by delays in our offer landscape.

Please check the process status of your request.

Update 12:58 Since 12:20 the issue is solved

Since midnight we have delays in our offer landscape, leading to time-outs. Please check the process-status of your requests and re-send your requests in case they timed out. We will update this post once the issue is resolved

Update 12:00 Everything is stable again since about 1 hour

We're excited to announce the launch of our Advertising API roadmap!

This roadmap serves as your compass, outlining the exciting features and functionalities we're developing for our advertisers.

Why a Public Roadmap?

Transparency is key. By making our roadmap public, we aim to:

• Align with your goals: See how upcoming features can enhance your advertising strategies and campaigns.
• Assist in planning: Get a glimpse into what's next and help you plan your upcoming development tasks.
• Open communication: Provide a platform for feedback and discussions around our API development.

What to Expect on the Roadmap?

Our roadmap is a dynamic document that will be continuously updated. Here's a taste of what you'll find:

• Planned: Get a sneak peek at up and coming functionalities.
• Considered: Whats on our radar and considered.
• Launched: List of recently launched features.

Stay Updated, Stay Ahead

Visit our advertising API documentation page to access the roadmap and stay informed about the latest developments. We're committed to building a robust and user-friendly advertising platform, and your input is invaluable.

Together, let's navigate the ever-evolving advertising landscape and unlock new possibilities!

To bring our API innovations to you faster, Bol is changing the release cycle of the Retailer API as well as the Advertiser API. This was announced on our Developer Portal.

To facilitate this change to our release cycle, we will also split our API Specs into separate specs per resource. This change will take place on the 1st of May of 2024. This will not affect the way you interact with our API. However, if you use the specs to generate a client to interact with Bol, you will need to adapt to this split.

To give you the time to make your changes, we will support the old API Specs for another 12 months, as is mentioned in our terms and conditions.

As previously announced, there will be a significant change to the release cycle of the Retailer API and the Advertising API. As of 2024, bol will no longer schedule full API releases every 6 months. Instead, version updates will be applied to resources if and when needed. With this change we aim to reduce the number of required migrations for partners, as well as increase the number of valuable features that will be launched in the future. 

Versioning per resource

The Retailer API is divided into a number of different resources, such as the Offers resource and the Product Content resource. Each of these resources will be kept up to date by having its own version starting at v10 for the Retailer API and v11 for the Advertising API. The benefit of this approach is that users only have to upgrade resources if there is something changing in their implementation. Additionally, a resource will remain stable as long as no breaking changes are introduced.

Major changes require a version upgrade

Resources will be updated to a new version as soon as a breaking change is introduced to one or more of the endpoints in that resource.

Minor changes to existing version

Minor changes to one or more endpoints that will not break existing implementations, can be introduced at any time. Under normal circumstances these releases will not require any downtime. Examples of minor changes include:

• Adding new optional fields to a request body, provided this doesn’t change the endpoint behavior.
• Adding new optional query parameters to the request, provided they don’t change endpoint behavior and have well-defined default values.

Announcing new versions

New versions will only be released if breaking changes are introduced to a certain resource. These planned version updates will then be posted on our Developers Portal at least 14 days before release. The developer portal gives the option of following our RSS feed to keep track of any changes or known issues.

Minor changes that will not break existing implementations will not require an upgrade to a resource version. However, these improvements will be posted on the Developers Portal.

Deprecated versions

Whenever a new version of a particular resource is released, the resource it supersedes is marked as deprecated and will be scheduled for removal after a minimum support period of 12 months, in accordance with our Terms of Service. The support period for deprecated resources in the Advertising API is currently set at 3 months. During this Deprecation stage, the Retailer API will be fully supported and all endpoints will remain active until their final removal.

Migration

To use the benefits of the new release cycle, it is necessary to migrate to the latest version, the Retailer API v10. Users of v7/v8 have to migrate before May 1st 2024. Users of v9 have to migrate before November 1st 2024.

Please note that users of the Advertiser API might need to migrate to v11 earlier based on their batch. Please see this page for more information.

To help you with the migration, we created this overview of breaking changes between v7/v8/v9 and v10.

In depth migration guides can be found here:

v7-v8

v8-v9

v9-v10

Questions?

retailer-api-migratie@bol.com

From July 1, 2024, the OrderIds and OrderItemIds will become alphanumeric. This means that they no longer only consist of numbers but can also contain letters. The OrderItemIds also become longer. Below we explain in more detail what exactly will change.

The OrderId becomes alphanumeric
The OrderId is the unique identifier of an order. We communicate this not only internally at bol, but also to partners and customers. Since the beginning, we only use numbers in the OrderId field. As of July 1, letters will be added, so the OrderId will become alphanumeric. The length will remain the same.

Example current format OrderId:
1648392093

Example new format OrderId:
A42C7WX5D2

The OrderItemId becomes longer and can contain letters
The OrderItemId is the unique identifier of an item within an order. Currently, there are always 14 numbers in the OrderItemId field. As of July 1, this field will no longer only consist of numbers, but can also contain letters. From this date, the field can also contain more than 14 characters.

Example current format OrderItemId:
16483920931002

Example new format OrderItemId:
342C-7W15-D2

Nothing changes for API users
The fields in the API remain textual. So if you use the API, the mentioned changes will not impact you. In versions 8, 9, and 10 of the API, both fields are already defined as 'string'.

To be on the safe side, please check whether your systems can deal with the changes. Check whether your systems and processes can handle an OrderId and an OrderItemId that have characters other than numbers. Also, check whether they can have a variable length.

From April 1, bol will already create some orders with the new textual values. Three months later, this will be the standard for all orders on the bol platform.

From April 3rd, there will be a change for sponsored products campaigns running in the bol-app. We will be using a different method of measuring when attributing impressions to a campaign. This change should result in more specific and logical insights into your results. This change may lead to a higher number of impressions within your campaign, which could result in a change in your click-through rate (CTR). We advise you to monitor your results closely in the coming period and take action if you notice that your campaign goals are not being achieved.

FAQ

Why is this change taking place?

We are now adopting the same measurement approach in the bol-app as in the web version. This ensures consistency. Additionally, this measurement method is more specific, resulting in better and more logical insights into your results.

Could this change also have a negative effect on the campaigns?

This method of measurement may result in impressions being attributed to your campaign more quickly. This could potentially lead to a lower click-through rate (CTR). This change applies to every advertiser and will not have any adverse effects on you as an advertiser specifically.

Can we provide a specific example of this change?

• Old situation: If a user scrolls in the bol-app and sees the same sponsored products appearing at different positions, only one impression is currently measured.
• New situation: If a user scrolls in the bol-app and sees the same sponsored products appearing at different positions, each time a sponsored product ad is viewed, one impression is measured.

We are investigating problems with retrieving commission information. This can affect the commission endpoint, and the commission information in the GET orders + shipments endpoints

Update: This issue has been fixed since 14:11

Currently we are having an issue with processing of orders. About 8% of the requests fail. This is related with a release this morning, it will be rolled back right now.

10:14 The issue has been resolved

Tomorrow morning (coming night) between 1 AM and 4:30 AM, we will have maintenance for our orders and shipments endpoints. This means it will not be possible to process orders. Apologies for the inconvenience.

Update 08:22 we need 10 minutes additional downtime in the coming hour. Apologies for the inconvenience

From April 18th, we will stop supporting certain weak ciphers. This will make us compliant with the PCI DSS standard.

More concrete; We will move from the ‘modern’ profile to the ‘restricted’ profile on our loadbalancers: https://cloud.google.com/load-balancing/docs/ssl-policies-concepts

Please make sure your software is compatible with this profile.

We are thrilled to announce a new advertising solution which we are working on, including a brand-new API for sponsored products.

Important documents to get started.

• Functional and Technical Documentation
• New Advertising API – Everything you want to know

Important milestones

• Early Adopter-phase - Preparation phase: April 2024
• Early Adopter-phase - Go-live phase: May 2024
• Transition batch 1 - Preparation phase: June 2024
• Transition batch 1 - Go-live phase: July 2024
• Transition batch 2 - Preparation phase: August 2024
• Transition batch 2 - Go-live phase: End of August 2024

Exact migration dates 

The date by when you need to be migrated is available via the Migration API per advertiser.

Early access for testing – Get in Touch

Ready to explore the potential of the new API? Want to start your development on the new API? Let us know by emailing us at advertiserapi-beta@bol.com and we’ll be in touch regarding possibilities to sign up for early testing access.

Stay tuned on developers.bol.com & partner platform for more updates in the coming months.

As communicated in previous  news items, bol is launching a brand new Advertising API. If you would like to continue using functionalities that are currently in the Advertising API, please migrate to the new API endpoints.

Migration
We understand that migrating to a new API can be challenging, so we have created a document which include key differences and a FAQ to make the process as smooth as possible. Please find it here:

New Advertising API – Everything you want to know

Migration timelines

The date by when you need to be migrated are available via the Migration API per advertiser.

Questions?

If you have any questions about migrating from the Current API to the New API endpoints, please send an email to: advertiserapi-beta@bol.com.

Currently, it is not possible to process / cancel orders. This affects API, but also the Seller dashboard. We are investigating with emergency priority.

Update 11:00

We still experience the same issue, at 12:30 we will update you with hopefully more information. For now we advise you to don't do anything with these orders.

Update 13:45

Orders and cancellation can be processed, we are still resourcing some old orders. It could be possible that an order will be available later.

Update 16:00

Everything is back to normal, we advise you to double check all the open orders if you don't miss anything. Also check your process-status of the confirmed orders of today. All the order confirmation till 13:45 where end up in timeout and therefore not been confirmed.

For more information you van visit our partnerplatform page.

We are looking for as much input as possible to determine our plans for the future of the Retailer API. With your feedback, we want to introduce new features, improve our documentation and improve our services

Are you responsible for building/maintaining a connection with our Retailer API and haven't filled in our yearly Survey yet?

Please do so now: LINK

We're thrilled to bring you an exciting update that opens up new horizons for your e-commerce journey! Introducing the "Product Rankings & Impressions" endpoint, a powerful tool designed to revolutionize the way you analyze and optimize product positioning and visibility on bol.com.

🔍Unlock the Power of Data

🛠️For Our Technical Users: Elevate Your Strategies

📊Data-Driven Decisions: Your Path to Success

With the "Product Rankings & Impressions" endpoint, you have the power to make informed decisions, enhance your product strategies, and optimize your presence on bol.

For detailed technical documentation, visit our API documentation section.

Exciting news from bol! We're rolling out a beta version of our
updated Commissions Endpoint API, designed to revolutionize how
retailers access commission rates. This enhancement focuses on
simplifying the retrieval of commission data for products identified by
their European Article Number (EAN).
Key Features of the Beta Commissions Endpoint API

• EAN-Based Product Analysis: Easily submit a list of EANs and
  receive detailed commission rates for each valid product.
• Optimized Query Handling: Experience improved data delivery
  on successful queries and clearer explanations for any failures.
• Simplified Commission Calculation: The API uses a
  straightforward formula, CommissionExclusiveVAT = FixedFee +
  (UnitPriceInclusiveVAT * Percentage).
• VAT Transparency: All monetary fields in the API response clearly
  indicate VAT inclusion or exclusion.

As this is a beta release, we're eager to gather feedback to further refine
and enhance its capabilities. This update is part of our commitment to
providing our partners with efficient, user-friendly tools for their business
needs.

Retailers can now access up-to-date commission information more
efficiently, aiding in effective pricing strategies. We invite our partners to
explore this beta version and share their experiences.
For more information and to start using the beta Commissions Endpoint
API, visit our API Documentation.

The Retailer information endpoint has received some changes.

The following fields have been added to the response body:

• Company name
• VAT number
• KVK number

You can use these fields to offer merchants a buttery-smooth onboarding process. Gone are the days of manually entering these fields. Fetch the existing data from bol!

This improves the experience of your users by reducing manual data input, and it reduces the chances of errors happening due to mismatching information.

These fields have been added to the existing GA endpoint. This means that you do not need to migrate to a new (beta/preview) version of the endpoint to benefit from them!

This approach contrasts with how we have operated in the past. Where any change, even non-breaking, would require a new version to be implemented.

By taking this approach we hope to reduce the time you need to invest to benefit from new features. This approach is a result of our renewed versioning strategy (1, 2).

But that is not all!

Ever want to make sure that you are using the right API keys for the right retailer? Verify if you are currently using a retailer's right account? Just want to double check and be 100% sure?

We’ve got you!

You can now use the Retailer information endpoint to fetch your own retailer id.

If you enter ‘current’ as retailer id parameter, we will derive the retailer id from your credentials and return the response as if you had entered your own retailer id.

Since 08:55 we experience an issue with orders and shipment. You are not able to retrieve orders and shipment and confirm orders.

We are working on a solution

Update 13:45:

We still experience the same issue, we hope to solve this as soon as possible.

Update 18:00:

Looks like the issue is resolving, all the order confirmation where the process status ended up in timeout with the message: after exceeding 1800 seconds of unsuccessful processing attempts will be processed, we advise you to double check the open orders. For all partner impact we refer to this page on partnerplatform, this page will be updated for all partner related updates.

Update 21:45:

Everything is back to normal.

More and more of our partners are using notifications to stay on top of their Bol assortment and offers. However, sometimes notifications are not successfully delivered to their destination. As these subscriptions stay active, this leads to recurring errors. To reduce these errors, notifications that are not delivered for an extended period will be disabled, starting at 18 December 2023.

You can check the status of your subscription via the Get subscriptions endpoint. You can also re-enable a disabled subscription via the Update Event Notification Subscription endpoint.

The conditions under which we disable subscriptions are as follows:

1. For WEBHOOK subscription types

a. Whenever the endpoint returns a non-success response code (anything other than a 2xx status code is regarded as a failure)

b. Whenever the endpoint takes longer than 5 seconds to process the request

2. For GCP_PUBSUB subscription types

a. Whenever the delivery fails due to authentication problems

b. Whenever the project cannot be found

For all the above scenarios, we will retry delivery 10 times over a period of 10 minutes. Should the destination of the subscription be unreachable for that time frame, we will automatically disable the subscription.

Please find the functional documentation here

Since 10:30 this morning we are experiencing multiple problems with creating new orders, processing orders, and finding shipments. We are working to find a solution ASAP.

Update 12:30:

Unfortunately we are still having this issue. We are expecting everything will be back to normal in 30 minutes. If so, we will update this notification directly.

Update 13:20:

The issue still isn't resolved, we're working hard for a solution.

Update 16:20:

Everything is back to normal, for partner impact you can check this message on partnerplatform.

Since this morning we experience an issue with orders and VVB.

It could be possible that your order confirmation or cancellation is failed, we advise you to check your process-status.

For some VVB orders it could be possible that the delivery-options are empty.

We are working on a solution.

Update 11:50:

Everything is back to normal.

We are experiencing issues with DHL VVB labels, especially DHL-SD. Please retry your request. Apologies for the inconvenience

Update: Problem has been fixed since 10:15

Since this morning it could be possible that the delivery-options is empty for some vvb orders. Therefore it is impossible to confirm these orders.

We are working on a solution, we will update this notification.

Update 11:10:

Issue is been resolved.

In some cases multiple delivery options are being recommended instead of one.

We are investigating and will update you

14-11-2023 15:48

A fix is being tested and we expect to release it anytime soon. This post will be updated when the fix is live

16-11-2023 15:25

Unfortunately the fix is delayed because of other dependencies. We hope to release the fix before the weekend. Apologies for the delay

17-11-2023 15:39

The fix has been released and the issue should be resolved

There are delays in our offer landscape and time-outs are happening. Please check the process-status of your request

Update 15-11 09:00

Since yesterday evening the delays disappeared. Please check the process status of your request and resend the requests if necessary

On Tuesday 07-11 around 07:00 AM, it will not be possible to use all orders and shipment endpoints for 15 minutes at most.

Apologies for the inconvenience

Update:

Unfortunately where where not able to do it on 07-11 we'll do it tomorrow 08-11 same time.

Contrary to this post, the maintenance took place this morning. Therefore it wasn't possible to process returns between 5 and 7AM.

Please check the process-status of your request. Apologies for not informing about the rescheduling of this maintenance

Do you want your repricer to avoid losing the buybox at all?

We now have a solution for you!

We have recently gone live with two new subscription betas.

Competing offer notifications

This subscription allows you to get a notification whenever anything changes in the response of the competing offer endpoint. This means that there has been a change in the competitive landscape for a given product.

A notification from this subscription can mean the following things:

• You have gained/lost the buybox.
• You have gained/lost a competitor.
• Your competitor has increased/lowered their price.
• Your competitor has changed their delivery promise.
• And more!

Using these notifications, you are better suited to stay in control over your competition. You can keep track of changes and attempts to gain the buybox by your competition. This provides you the ability to proactively respond to changes instead of only reacting to losing the buybox.

If you do unfortunately lose the buybox, these notifications will let you respond much faster than the typical reaction time that we currently see.

This reaction time improvement can already help your repricer be the best one in the upcoming 2023 season!🎁

For more information see the functional documentation.

Price star boundary notifications

Keeping track of your competition and the buybox is crucial. However, so is having a great price in the market.

Having a good price helps in getting a better search rank, a higher conversion and Google Ads paid for by bol. 

Prices in the market are constantly changing. As a result, so are the price star boundaries of a product.

To help you keep a good price in the market, we want to send you a notification whenever the price star boundaries of a product that you sell change. This removes the need for constantly polling the GET endpoint and possibly knowing about a change too late.

For more information see the functional documentation.

New delivery method

Both new subscription event types are currently available with the Google Cloud Platform (GCP) Pub/Sub delivery method.

Excited about these new features? Any questions?

Get in touch subscriptions-beta@bol.com 

Tuesday 31st October between 5AM and 7AM it will not be possible to handle/create returns.

Apologies for the inconvience

Since 13:30 invoice uploads are timing out. We are investigating

Update

Because of the low impact, this will only be fixed on monday.

Update

The issue lasted about 1,5 hours and was mainly feedback related. The invoices were in fact uploaded.

Since last Friday 20-10-2023 it could be possible that you're receing an error message in the API settings and therefore you can't create credentials.

Unfortunately, there isn't a workaround we're working on a solution.

Because of an issue with DHL it is impossible to purchase DHL labels (VVB) now

Update 11:10

DHL fixed the problem and the label process should work again

This morning, requests to upload invoices regularly timed out. Please check the process status of your request. The issue has been fixed.

Update 17:02

It seems that just the feedback was impacted. Apologies for the inconvenience

As communicated in previous news items, the Open API will no longer be supported for (retailer) partners as of today October 16, 2023. The Open API will be turned off around 10 AM.

Migration guide
We understand that migrating to a new API can be challenging, so we have created a migration guide to make the process as smooth as possible. The new Retailer API endpoints are designed to align with the conventions and principles of the Retailer API, and thus have a different setup compared to the Open API. To assist you, we have included an endpoint mapping, object mapping, and an FAQ section to provide an overview of the key changes.

Questions?
If you have any questions about migrating from the Open API to the Retailer API endpoints, please send an email to:

openapi-migratie@bol.com.

A new version of the Retailer API has been released on 29th September 2023.

The Retailer API version 10 introduces eminent new features and significant improvements in the API.

Advertising API

• The following resources of Advertising API have not been migrated to v10:
  • Ad Groups
  • Assortments
  • Campaigns
  • Keywords
  • Negative Keywords
  • Target Products

For more information on why these resources have not been migrated, see here.

For a comprehensive list of frequently asked questions pertaining to this transition, see here.

• The Reporting resource remains in Beta and is migrated to v10 of the API.

Retailer API

The following resources of Retailer API offers significant improvements:

Insights and Products

• The Get price star boundaries by EAN endpoint has moved out of Beta and has been relocated from the Insights resource to the Products resource in v10 of the Retailer API.
• The Get a list of competing offers by EAN endpoint of the Products resource offers updates to the maxDeliveryDate field in the response. v10 onwards, the maxDeliveryDate field is no longer mandatory, and hence there will be no utilization of the placeholder date.

Orders and Shipments

• The Ship order item endpoint has been relocated from the Orders resource and has been added as Create a shipment to the Shipments resource.
• A new quantity field is added to the request body of the Create a shipment endpoint of the Shipments resource and it supports multiple objects in the orderItems array. Consequently, starting from version 10 onwards, it is possible to split an order item into multiple shipments and purchase multiple shipping labels for a single order item.
• A new enum value, INBOUND_COLLECT has been added to the response body of Get a shipment by shipment id endpoint of the Shipments resource.
• The Beta endpoints Get a list of invoice requests and Upload an invoice for shipment id have moved out of Beta and are migrated to v10 of the Retailer API.

Shipping Labels

• The endpoints Create a shipping label and Get delivery options offer the following updates:
  • A new quantity field is added to the request body.
  • Support multiple objects in the orderItems array.

Shared API

• A new event type CREATE_SHIPMENT has been added to the request body of Get the status of an asynchronous process by entity id and event type for a retailer endpoint.

For more information on the improvements, see the v10 functional documentation.

For more information about the overview of the changes, see v10 Release Notes.

Upgrade from v9 to leverage the advantages of the enhanced designs and features in the new v10 API. For more information, see v9-v10 migration guides.

Between 15:15 and 16:15 some ship order item calls ended up in a timeout.

Please check the process status id of the orders to check if your orders are confirmed or not, If not please ship them again.

Revision of the Retailer API versioning strategy
In 2020 we introduced the 'Retailer API lifecycle': a fixed rhythm in which new API versions with new functionalities are released every 6 months and old versions are phased out after 19 months. By regularly releasing and removing API versions, partners have been able to plan the migration to a new version well since 2020.

In addition to the positive aspect of the current API lifecycle, we also received feedback that the mandatory upgrade to a new version within 19 months sometimes takes a lot of time and new functionalities are not always used. That is why we are reviewing the way we release and remove API versions. Partners who are not interested in new functionalities will only have to switch to a new version in the future when there is a breaking change. The new API versioning strategy will be further elaborated and implemented in the coming six months. At the beginning of 2024, more information about the new strategy will be shared via developers.bol.com and the Partnerplatform.

Redirect from API v7 to API v8
Are you still using API v7? Then API v7 requests will be automatically redirected to API v8 from November 1, 2023, until May 1, 2024. This means that you can continue to use API v7 for a longer period of time and you will receive responses from API v8 as of November 1. At the beginning of next year, we will announce what the new API versioning strategy will look like and from which API version we will no longer release periodic updates. After this, API v7 users can migrate to this 'base version' at once. This will save an extra migration in the coming months.

We are investigating an issue with GET single order requests giving 500 errors.

It should be fixed, but we are monitoring the situation

We are currently investigating an incident related to the Retailer API with emergency priority. This is an automatically generated post. More details will follow on the next office day.

Update: Our Retailer API was not functioning properly between 17:07 and 17:15. Please check the process status of your request and retry if it failed or timed out. Apologies for the inconvenience

About 1 hour ago we faced time-outs for offer endpoints. Please check the process status of your request, if you calls had failed you need to do it again. We will advise you to do this after this issue is resolved.

We are currently working on a solution.

Update 18:15: Everything is back to normal

We are investigating an issue with return handling. This post will be updated once we know more

16:21 We identified the issue and are working on a quick fix

16:29 The issue has been fixed. Please retry your requests to succesfully process the missed returns. Between 06:17 this morning and 16:17 we did not process any returns. Apologies for this inconvenience.

03-08, 11:15
An increase of 500 errors for retrieving FBB shipments is being investigated with high priority. Further updates will be posted on this page.

03-08, 17:20
A fix has been implemented. The 500 errors are currently decreasing. We will continue to monitor it and post a final update once it has been fully resolved.

08-08, 12:30
A new fix has been implemented. This has reduced the 500 errors further, but unfortunately, the issue has not yet been completely resolved. We are working on a new fix.

Wednesday, Aug 23rd, a change will be made in our IT infrastructure of our API application. This will happen between 6 AM and 8:30 AM. We don't expect downtime, but the following can be expected:

• Process-status id's will start counting from 0
• During the release window a delay can be expected with retrieving a process-status

Please inform us if you notice unexpected behavior.

Currently an issue with the generation of labels is being investigated with emergency priority. LINK

Update 13:22 The issue has been fixed and it should be possible to generate/download the labels. The impact was limited to orders with delivery date today and transporter BUDBEE.

Apologies for the inconvenience

August 1, between 05:30 and 07:00, our Orders endpoints will not work. The downtime will last a maximum of 90 minutes. During the downtime, all order endpoints will not work, which means:

- New orders (both FBR and FBB) will not appear;

- No shipments are processed;

- No cancellations are processed.

It is also not possible to retrieve returns during the downtime. It will still be possible to handle or create returns.

About 1 hour ago we faced time-outs for offer endpoints. Please check the process status of your request.

Right now the problem was already solved, but previous requests could have failed (between 11:30 and 12:00)

An increase of 502's is being investigated with high priority

18:34

We managed to identify the root cause and the problem has been fixed

12:13

Since 11:15 we are seeing time-outs on requests to ship orders. This is currently being investigated with emergency priority.

13:02

Incident has been fixed since 12:40. All shipments have been processed, so the time-outs can be ignored

An unexpected consequence of an infrastructure change this morning is that GET requests with an empty body are receiving a 400 Bad Request: Your client has issued a malformed or illegal request. To fix this, please send the request without body

Apologies for the inconvenience

As previously announced on this page and this page, from July 1, 2023 it will no longer be possible to access the Open API with API-keys. After this date, it will only be possible to use JWTs for Open API authentication.

Please note: the Open API will soon no longer be supported for retailers. For more information, please visit this page. We recommend that you migrate from the Open API to the replacement endpoints in the Retailer API v9 soon. The rate limits on the replacing endpoints will be increased to acceptable levels before July 17th.

09:38

An issue with inaccurate results for the search endpoint is being investigated. More details will follow

11:30

The issue has been resolved. Apologies for the inconvenience

June 27th

20:15

Time-outs can be experienced when shipping / cancelling orders. This is currently being investigated

20:34

Issue is being investigated with emergency priority

21:46

The issue was just related with the feedback. Order items have been correctly shipped in our back end. The process status time-out can be ignored. We will continue to investigate the feedback mechanism tomorrow morning and update this post

June 28th

08:18

Another consequence is that FBB/Lvb orders are not being exposed since 18:27 yesterday evening

08:49

The status of orders is not up-to-date in the orders endpoints. This means that orders that were shipped since 18:27 yesterday had no status update in those endpoints. In the SDD the status is accurate and we are working on updating the orders endpoints as soon as possible

09:28

The cause of the issue has been fixed around 09:15. Unexpected time-outs for shipping/cancelling orders are gone since that moment. We also started to process the missed status updates (and FBB/Lvb orders) in the orders endpoints

10:46

Missed order updates and Lvb orders are still being updated. We will give a final update to this post when it's done. Expectation is around or just after lunch

11:34

Issue is resolved. All information in the orders endpoints should be accurate now. Apologies for the inconvenience

Right now, performance issues on the Open API (catalog endpoints) are investigated

Delayed responses and time-outs can be expected.

This post will be updated

Update 13:40 Issue has been fixed and response times will recover now

Because of a large change in our IT-infrastructure we are facing time-outs on several endpoints. Please check the process-status of your request. This started yesterday 20th of June 14:38. Because of our offer issue, we didn't notice it. It seems that we just fixed the issue, but will confirm this later.

Apologies for the inconvenience.

Update 14:30:

Everything is back to normal.

Our offer queues are high at the moment which could cause time-outs for offer creates/updates/deletes. Please check the process status of your requests

Update 17:00 This specific issue was fixed

Over the last months, we have worked hard to increase the rate limits of the new endpoints in Retailer API v9 with Open API functionality (including Competing offers). At the moment, we are confident that by July 17 the rate limits will be at least the same level as for the Open API. If possible, we will increase the rate limits earlier. If this is the case, we will inform you via a news item on developers.bol.com.

If you have any questions, please contact your technical contact at bol.com or openapi-migratie@bol.com.

Since this afternoon we experience a delay on processing product content. We think this will stay the whole weekend. We try to process everything as fast as possible. Check the upload-report what the status is of the content call.

Since this morning we experience an issue with processing assets. Due this incident it could be possible your assets are declined.

We will update this notification when we have more information.

Update 18:00:

Unfortunately, we're not able to fix this issue today. Monday morning will be the next update.

Update 16-05 11:00:

Everything is back to normal, all the assets that already declined need to be resent to process.

In recent months, bol.com has been working hard on the development of two important features in the Retailer API: price stars and Open API functionalities. In this article, we would like to inform you about new developments regarding these features.

We want to give our partners assurance that our endpoints are of high quality. During beta testing we learned a lot about using the beta endpoints. We received a lot of positive feedback and have updated the endpoints in response to suggestions for improvement. We also noticed that the traffic on both endpoints - which are not retailer specific - is (much) higher than anticipated. Scaling up to handle this peak load is very challenging. That is why we unfortunately couldn't make all endpoints from the beta General Available yet in the v9.

This is the current situation:

The endpoints with Open API functionality (including Competing Offers) have become generally available in the v9.
These endpoints contain direct value for almost all partners. We initially launched with the current limited rate limits, after which these will be increased as soon as possible as bol.com can scale up further.

Important: We advise to start researching the new endpoints now and prepare in Q2 for the migration from the Open API to the Retailer API. Use this period to test and migrate repricers and other functionalities that use the data from the Open API. Once the Retailer API rate limits are increased, we will have a three-month period where the Open API will run in parallel with the replacement endpoints in the Retailer API.

The Price star endpoint has remained in beta for the v10
We still have every intention of making this endpoint generally available. However, in combination with the other endpoints, we expect a peak load. By keeping this endpoint in beta for longer, we have more control over its use.

We are of course working on various solutions to scale up our API. The further progress of the project is unfortunately still difficult to predict at the moment. We will communicate again about progress by 9 May at the latest.

Improved predictability rate limits Open API

Yesterday around 13:00 we updated the way we were rate limiting for the Open API. The individual rate limits remained the same. The changes creates more predictability in rate limiting. We hope this will make traffic toward those endpoints more efficient.

As of 1st of July, we will stop supporting the use of API-keys as an authentication method for catalog endpoints (Open API).

If you are still using such keys, please migrate to JWT using Retailer API credentials created in your seller dashboard.

More info (in Dutch) here and here

A new version of the Retailer API has been released on 1st April 2023.

The Retailer API version 9 introduces eminent new features and significant improvements in the API.

New features:

Reporting - Following endpoints continue to remain in Beta and are now available in v10 (Beta) in the Reporting resource of the Advertiser API:

• Request a share of voice report for categories - Offers share of voice report for a campaign on a category level.
• Request a share of voice report for search terms - Offers share of voice report for a campaign on search term level.
• Retrieve a share of voice report by report id - Retrieves a share of voice report based on the report ID.

For more information on the aforementioned endpoints, see the functional documentation.

Shipments - Following endpoints continue to remain in Beta and are now available in v10 (Beta) in the Shipments resource of the Retailer API:

• Get a list of invoice requests - Retrieves a list of all the invoice requests received from customers.
• Upload an invoice for shipment id - Uploads an invoice associated with a shipment.

For more information on the aforementioned endpoints, see the functional documentation.

Insights - Following endpoint continues to remain in Beta and is now available in v10 (Beta) in the Insights resource of the Retailer API:

• Get price star boundaries by EAN - Offers an indication of the price performance levels of your products.

For more information on the aforementioned endpoint, see the functional documentation.

Products - Following endpoints moved out of Beta and are now available in v9 (GA) in the Products resource of the Retailer API:

• Get a list of competing offers by EAN - Provides the competitiveness of the active offers in detail.
• Get product ids by EAN - Provides the bol.com product ID and the EANs associated with the product.
• Get product placement - Provides information about a product’s location and the categories under which it is currently listed.
• Get product list filters - Provides the filter options and categories for a product on the webshop.
• Get product list - Provides insights on the current position of a product within categories or on the search results pages for the specified country.
• Get product assets - Provides information about image assets of a product on the webshop.
• Get product ratings - Provides the ratings for a product on the webshop.

For more information on the aforementioned endpoints, see the functional documentation.

Retailers - Following endpoints moved out of Beta and are now available in v9 (GA) in the Retailers resource of the Retailer API:

• Get retailer information by retailer id - Provides the customer ratings and reviews for a specific retailer within bol.com.

For more information on the aforementioned endpoints, see the functional documentation.

Improvements:

Invoices – Following endpoint includes changes in the response body of the API.

• Get all invoices - The enum value for invoiceType field has been renamed from BOL_RETAIL_MEDIA_GROUP (BRMG) to ADVERTISING_VIA_BOL (Avb).

For more information on the aforementioned endpoints, see the functional documentation.

For more information about the overview of the changes, see v9 (GA) and v10 (Beta) Release Notes.

Upgrade from v8 to leverage the advantages of the enhanced designs and features in the new v9 API. For more information, see v8-v9 migration guides.

This morning between 09:30 and 10:30 we faced a long offer processing queue. This caused a lot of time-outs on offer updates / creates / deletes.

Please check the process-status of your offer requests.

Our apologies for the late notice.

As of May 1st 2023 the following fields will no longer be populated in the OpenAPI (catalog endpoints):

• useWarrantyRepairConditions (Signals whether the warrantyConditions and repairConditions apply to this seller)
• warrantyConditions (Specific return warranty terms that the seller applies)
• repairConditions (Specific repair condition terms that the seller applies)

What will be the consequence of this change?

At this moment, the fields will not be deleted, but will return a default value for all requests.
There is no need to change your application is you do not rely on this field.

Why did bol.com introduce this change?

We have decided to make this change because these fields have very limited added value for our API users, but maintaining them require a considerable amount of effort.

These fields are important for my business, what can I do?

Please reach out to open-apimigratie@bol.com to share your use case and we contact you about this

Currently we notice increased time-outs on offer processes.

It's possible you will receive a time-out while creating, updating or deleting an offer

We will update once we know more

Update 13:57 We expect delays/time-outs to last for another hour, because we are dealing with a queue. Please check the process-status of your request. Please retry your request if it timed out. If possible wait with retrying until we let you know that the queue is gone

Update 14:53 Issue has been resolved. Please check the process-status and retry if the request timed out.

We are currently investigating slow response times and 504s on Open API Endpoints (catalog).

Update: About 10% of traffic to catalog endpoints result in 504's. Rest of traffic is slow (up to 4 seconds response time). This is being investigated with high priority

Update 2: Around 13:15 CET, the problem has been fixed and behavior is back to normal.

Apologies for the inconvenience.

Monday morning, 6-2-2023, several endpoints will have some downtime. This will last from 01:00 AM until 02:00 AM.

This will impact the entire Retailer API, and especially the following endpoints:

- Invoices

- Orders

- Shipments

Apologies for the inconvenience.

Today we have deployed two new beta endpoints to transfer retailer relevant Open API functionalities to Retailer API. Reason for this is that by Q3 of 2023 we will no longer be able to support the Open API fully.

For an overview of the new endpoints you can view this page.

We will keep you informed with news and updates in the future.

The two new beta endpoints are:

Product List

This functionality provides a list of products based on category, search term or filters that reflects the current ranking of a product within that list for the specified country on the webshop. For more information, see the functional documentation and Redoc.

Product list filters

This functionality provides the filter options and categories for a product on the bol.com webshop. It helps the customers refine their search results and find their desired product, based on a category or search term. For more information, see the functional documentation and Redoc.

From now on the following transportercodes are accepted for shipping order items

• TRUNKRS
• CYCLOON

The documentation will be updated soon

Since today it could be possible that on several endpoint you are receiving a 503 server unavailable.

We are investigation how this is possible.

When we have more information we will update this notification.

Update 14:00:
Due to a deployment we had some increased response time, everything is back to normal

Since this afternoon it could be happen that you are receiving more 503's on the retailer API.

We are working on a solution.

18:40:
Everything is back to normal

Tomorrow morning 16-02-2023 between 07:30 and 08:00 we will have downtime on our GET orders endpoint.

After 8:00 everything is back to normal.

Wednesday 08-02 between 07:00 and 08:00 we will have downtime on our orders and shipments endpoint. During the downtime, you are not able to receive or update orders.

After 08:00 everything is back to normal.

Tomorrow morning on 24-02-2023 between 07:00 and 07:15 we will have planned downtime on the Price star boundaries endpoint.

After 07:15 everything will be back to normal.

Price star boundaries endoint is current having issues. This may lead to slow response times and 50x's. We are investigating the issue

Update 16-02: Issue is resolved

Update 17-02 13:58: We are having issues again with price star boundaries endpoint.

Update 17:02 14:22: Seems table again. We will keep monitoring

The Retailer API v6 will be removed on May 1, 2023. Make sure you migrate to Retailer API v8 in time. It has a few important advantages.

Migrating yourself or through a third party

• If you have your own API integration, please use the migration guides below to migrate from Retailer API v6 to v8 (both migration guides are required for migrating to v8). Please be aware that IT knowledge is needed for the migration.
  
  > Migration guide v6 to v7
  > Migration guide v7 to v8
  
  Migrating from API v6 to v7 is also possible, although migrating directly to v8 is probably a better option. API v7 will be turned off on November 1, 2023. API v8 will be switched off on May 1, 2024. Also, consider the IT time required to migrate. Depending on the integration with your systems, this can take up to a few weeks.

• Do you use one of the third parties listed on this page? Then you don't have to take any action yourself, you will automatically switch to the next API version. Make sure your API integration is adjusted well in time, so it still works properly after May 1st.
  

How do I know which API version I'm using?
In the Accept header of your API requests, you can see which version you are using, among other things. Is it not possible to view this yourself? Please ask your technical contact or integration partner which version you are using.

Benefits of the Retailer API v8
The Retailer API v8 has some significant improvements and new functionalities compared to v6 and v7. For example, via v8 you can retrieve available product information, offers that are offline, and product category recommendations. With API v8 you can also retrieve orders in a more efficient way.

Release planning
Would you like to know when you can expect further API updates? Or when existing API versions are phased out? You can find this information in the API release schedule. Keep an eye on this schedule to know when to migrate to the next API version.

Tomorrow morning between 07:45 and 08:00 we will have downtime on our GET orders endpoint.

After 8:00 everything is back to normal.

We are currently developing new endpoints to transfer retailer relevant Open API functionalities to Retailer API. Reason for this is that by Q3 of 2023 we will no longer be able to support the Open API fully. If you're using Open API endpoints, it’s beneficial to switch over to Retailer API before July 1st to ensure stability and support.

More information about these new endpoints can be found on our new page.

We will keep you informed with news and updates in the future.

Tomorrow between 6:00 AM and 6:30 AM we expect around 5 minutes of downtime.

During the downtime it will not be possible to

- Retrieve orders

- Process orders

- Download shipping labels

Apologies for the inconvenience

Yesterday's data is missing for the offer insights. This means that the endpoint is not giving accurate responses. The issue is under investigation.

Update: Around 17:00 yesterday the issue has been resolved and from that moment on the data in the offer insights endpoint was accurate again

Since last week it could be possible that you experience an issue with the POST shipping-label. The process status of this call stay in pending and then ended in failure or timeout.

We are working on a solution.

Update 13:45:
There where two reasons this issue could happen, one is resolved.
Another reason this issue can happen is because the shippinglabel is not available yet. This is because we are prevent for to early handover to the transporter. In the v8 POST deliveryoptions we have created the attribute: earliestHandoverDateTime for when the label is available.
We are currently working on a solution to prevent the process status go to timeout but to failure with errormessage

Since 15:00 we experience a outage with the Budbee and Ampere labels, therefor you can not create any label for these transporters.

We will update this notification.

Update 15:30: Everything is back to normal

Since 7:00 we experience some issue with the offer export, therefore a lot of exports end up in timeout.

We are working on a solution.

Update 10:00:
Everything is back to normal.

Since 11:45 we experience an issue with vvb DHL labels, therefore you are not able to confirm orders with DHL.

We are working on a solution

Update 14:20: Issue is resolved

The Price star boundaries endpoint in the Insights API is rolled out for a pilot release program. This new feature enables you to retrieve information about the price stars boundaries of the product(s) based on their EAN(s).

For more information on Price star boundaries, refer to the functional documentation.

As per the current plan, Price star boundaries endpoint will become general available in v8 of the Retailer API.

For more information, refer to the Retailer API release planning.

Rate limiting on Open API seems to have an issue. We are investigating

Update 13:05

We will try to improve the performance. One possible solution will be to reduce the rate limits from 5 / second to 4 / second to better control the traffic.

Update 16:50

Because of black friday, we won't make any changes now. Please retry your requests until you get a response.

We are investigating an issue with emergency priority. Slower responses or 504's could be experienced for the following actions:

- Shipping/cancelling orders

- Retrieving shipping labels.

Update 14:18

The issue is resolved. Behaviour is back to normal

Tuesday 22-11 between 06:45 and 07:00 we will have a planned downtime on orders endpoint. During this downtime you are not able to confirm or cancel orders.

After 07:00 is everything back to normal.

We temporarily disabled Instabox as a carrier, because it was not possible to generate their labels. According to our information Instabox will not collect shipments today. We will keep you up-to-date in this post.

Update 13:22

For confirmed orders: Please ship the product with another carrier. Costs for the instabox labels/pickups will be refunded. This also applies to orders that were already brought to a drop-off point.

For open orders: Please don't ship the products. We are trying to find a solution for those orders

Update 17:47

Most instabox orders will be cancelled. Customers will be informed. Offers with VVB+ instabox delivery promise have been taken offline and will be online again when you change the delivery promise.

Apologies for the inconvenience of these measures

For more details (Dutch), click HERE

As per release schedule our Retailer API v5 will be removed tomorrow morning.

Migration guides

v5->v6

v5->v7

v7->v8

More info (Dutch)

LINK

Technical migration questions

retailer-api-v5-migratie@bol.com

Currently we are investigating issues with GET offer requests and missing offer information in responses from our Orders API.

Update 12:39

The issue is not solved yet. We are working on it with emergency priority

Update 13:57

The root cause has been identified and fixed. For new orders the offer information should be available. We are working on a fix to restore the data for older orders.

Update 15:37

For the orders affected by this issue earlier today we will not be able to complete the missing offer information in the GET single order requests. If this causes problems for your integration, we suggest 2 solutions:

Proposed solution 1 : Use the SDD (seller account) to confirm/send the order

Proposed solution 2: Complete the response manually with data from the offer export (the information is there for the relevant EANs)

Alternative: If this will not be possible for you, the alternative is to not fulfil the order. If this results in a strike, we will remove that strike. Please contact us for that

As per release schedule our Retailer API v5 will be removed 1st of November, next week.

Migration guides

v5->v6

v5->v7

v7->v8

More info (Dutch)

LINK

Technical migration questions

retailer-api-v5-migratie@bol.com

As a platform, we aim to constantly improve the bol.com Retailer API and the API developer experience. Therefore, your opinion about the Retailer API is very important to us.

Give your feedback now and make it count
Together we are continuously building and improving our platform. Your feedback is essential input to do this. It helps us to improve specific matters, such as technical documentation, API resources and technical support. Thus, fill out our survey and give your feedback, so we can get to work!

You will access the survey by clicking on the link below. The survey will take approximately 10 minutes to complete. Your response will be anonymous.

Give your opinion

We thank you in advance for your time and feedback!

There will be scheduled maintenance on the Retailer API on October 18 between 05:30 and 08:00. During this time, the Retailer API will be temporarily unavailable.

If requests fail during this maintenance window, please resend the original requests after 08:00.

We apologize for any inconvenience.

Due to an infrastructure failure from 17:53 until 18:06 we've failed to process most requests during this timeframe, causing them to time-out.

Please check the process-status of your manipulation requests (PUT/POST/DELETE)

Apologies for the inconvenience

Today our new RSS feed for the Retailer API went online.

All news items will now also be pushed via RSS. If you wish to be automatically updated on news regarding the Retailer API, please subscribe to https://developers.bol.com/en/feed

Kind regards,

The Retailer API team

We are investigating delays and time-outs on our Offer Export endpoint. Updates will follow in this post

Update 13:57

We identified the issue and we are working on a fix. When the fix is deployed, we will update the post

Update 16:45

The fix has been deployed and Offer Exports should not be getting delays and time-outs anymore

A new version of the Retailer API has been released on 1st October 2022.

The Retailer API version 8 introduces eminent new features and significant improvements in the API.

New features:

• Product Content API: Offers the following two new endpoints:
  • Get catalog product details by EAN - Retrieves the details of a catalog product by means of its EAN.
  • Get chunk recommendations - Retrieves a selected number of recommendations for a product. For more information on the aforementioned endpoints, see Get catalog product details by EAN and Get chunk recommendations v8 functional documentation.
• Replenishments API: Offers the following two new endpoints:
  • Request product destinations - Requests a list of product destinations by EANs.
  • Get product destinations by product destinations id - Retrieves the product destinations for one or more products by product destinations id. For more information on the aforementioned endpoints, see v8 functional documentation.
• Offers API: The following endpoints have moved out of Beta and are now available in v8 [GA] in Offers API of the Retailer API:
  • Request an unpublished offer report
  • Retrieve an unpublished offer report by report id. For more information about the Offers API, see v8 functional documentation.

Improvements:

• Orders API: Following new fields have been added to the Get a list of orders endpoint in the Orders API:
  • change-interval-minute - Retrieves a list of all the new and changed orders within the specified timeframe sorted by the time of the latest change.
  • latest-change-date - Retrieves a list of all the order items that were last changed on a given date for up to three months in the past.
• New fields added to the response body of Get a list of orders endpoint and Get an order by order id endpoint. For more information on the Orders API, see v8 functional documentation.
• Invoices API: Changes in supported media type formats.
• Changes to the request and body structures of the APIs. For more information about the overview of the changes, see v8 Release Notes.
• Changes in the functional documentation.

Upgrade from v7 to leverage the advantages of the enhanced designs and features in the new v8 API. For more information, see v7-v8 migration guides.

Since 12:30 we are returning 500 and 504 errors for the getProductPerformance and GetCampaigns endpoints of the Advertising API. We are working on a solution for the issue. We will post an update on this page once the issue has been resolved.

Update 17:15:

Everything is back to normal

Time-outs can be experienced on several endpoints. This is being investigated with highest priority. We will update this post when there is news

Update 10:29 The offer services have not fully recovered yet. Time-outs can still occur. Please check the process status of your requests

Update 10:50 Retailer API down for manipulation requests

Update 10:57 We are still experiencing issues and working to resolve the instability as soon as possible.

Update 11:28 Everything seems to be resolved, apologies for the inconvenience

Wednesday 7th of September between 6:00 and 07:00 we will have a short down time just for creating returns and cancelling orders.

Please check the process status of your requests to check whether we handled them

Incident description:

Since August 16th 15:05 there has been an ongoing issue with the Retailer API. This issue results in more ‘504 errors’ to be returned. We are working hard on a solution. Updates on the issue will be posted on this page. We apologize for the inconvenience.

Updates:

Update – 17th Aug 17:10

The issue appears to be resolved, title was changed accordingly. Thank you for your patience and cooperation.

Update – 17th Aug 16:00

The implemented solution appears to have resolved the issue. We'll continue monitoring and mark this as resolved if no issues have occured by EoD.

Update – 17th Aug 14:05

A solution is now implemented, we are verifying it's effectivity and improving resiliency.

Update – 17th Aug 12:40

We are closing in on the solution of the issue. However, due to the severity of the issue we might have to take actions that include downtime. We will keep you informed.

Update – 17th Aug 10:19

The issue is still going on. Retailer API and Open API give back 504's at a certain frequency. We are investigating with emergency priority.

Update – 16th Aug 22:15

Unfortunately, the issue seems to be broader and involves several endpoints. We will continue investigating tomorrow morning.

Update – 16th Aug 15:25

The issue is assumed to be resolved. Please check the process status of your requests. In case of a timeout, please retry the original request.

Since 14:30 there has been an ongoing issue with the Retailer and Open API. This issue results in more ‘504 errors’ to be returned. We are working hard on a solution. Updates on the issue will be posted on this page. We apologize for the inconvenience.

Update 17:15: Issue is resolved

Since a couple of days, it could be possible for a client to select a Pickup Point as shipping location for its order while this should not be the case. This is giving partners a wrong shipping address and will give an error when you would try to confirm the error. The following error could occur:

“Order with pickup point delivery with order item id’s [XXX] must be shipped with transporter code ‘TNT’.”

The IT team is looking into it.

Currently, we are facing an issue where the Create Offer Export could take longer to process. We are working on it.

Update 22-11 14:15

The issue seemed to be solved. Had any failing requests? Please retry your request.

Currently, we are having a small issue where the Billing Details in the open order could be missing. If so, please try to retrieve your open order again. We are working on it.

Right now there is an issue with creating shipping labels and confirming orders (about 5% of all requests end up in a failure/time-out)

Please check your process status

Retrying your request can result in a succesful request

Update 13:55 : The issue seems to be bigger; also GET orders is affected. The reponses can be incomplete. Items can be missing

Update 14:30 : The issue is resolved. Please check the list of open orders for new order items

We are delighted to announce that new order management features have been added to v8 (Preview) of the Retailer API. These features make the retrieval of order information more efficient and effortless.

The new features include:

• Addition of a new (optional) ‘change-interval-minute’ parameter in the Get a list of orders endpoint. It provides you with an easy access to only the new or changed orders within a given timeframe.
• Addition of a new (optional) ‘latest-change-date’ parameter in the Get a list of orders endpoint. It provides you access to all the orders (open, shipped or cancelled) that were last changed on a given date up to three months in the past. This parameter can be used for the purpose of incident management, for example after an outage.
• Addition of `SHIPPED` to the `status` query parameter of the Get a list of orders endpoint. Filtering on `status = SHIPPED` helps you keep track of orders fulfilled by bol.com more easily.
• Addition of `ALL` to the `fulfilment-method` query parameter of the Get a list of orders endpoint. It allows you to handle both Fulfilment by bol.com (FBB/LvB) and Fulfilment by retailer (FBR) orders with a single request.
• Cancellation requests appearing in the Get a list of orders endpoint, in addition to the Get an order by order id endpoint.

For more information about these features, refer to the functional documentation.

Between 13:00 and 14:00 VVB orders are appearing as non-VVB orders.

We can't change them to VVB. For more info: LINK

Apologies for the inconvenience

For some partners it could be possble that your are not able to create an offer export since 01-08-2022 .
You are receiving a error like "proces with similare specification is already active please wait untill te previous action has completed. status failure"

We are working on a solution.

Update 16:15: Issue is resolved

Since 14:15 we experience some delay on our offer endpoints. Therefore it could be possible that some creates, updates or deletes have some delay with publishing. It is also possible that a offer export end up in a 500 error.

We are working on a solution

Update 15:00:
Everthing is back to normal

Today a new version for the unpublished offer export and the offer export have been brought to production.

• For the unpublished offers export we now expose more than one reason why the offer is not published, if this is applicable to the offer. In addition, a few reasons were previously filtered out. From now on we expose all reasons why an offer is not published.
• The offers export will only change for V8, where an additional field has been added:
  • correctedstockAmount : The amount of items in stock minus handled order and minus open orders. As compared to the stock you sent us. When this reaches 0, your offer will not be for sale on the shop.

Further information can be found here.

Reminder that the legacy shipmentlabels will be terminated as of this monday August 1st for NL-NL shipments. As already adressed in two previous mails to partners who use this proposition.

!NB this does NOT concern the Distribution via bol.com (VvB) proposition!

Find more information in this article.

Since 16:45 we experience timeouts on offer create and update endpoints.

We are working on a solution

Update 17:35: it is also possible that you received a 500 for all offer calls.

Update 18:10: everthing is back to normal. It could be possible that some process status id end up in time out but the status was failure or succes.

Between 14:00 and 15:00 some offer update and create offer calls end up in a timeout.

Everything is now back to normal.

Do you offer an integration with Verzenden via bol.com? This summer we are launching Verzenden via bol.com with a new transporter: Ampère. For more information: https://partnerplatform.bol.com/nl/nieuws/bol-com-gaat-zelf-pakketjes-van-verkooppartners-ophalen/

Be aware that this will have some impact on the Verzenden via bol.com implementation, when retrieving Delivery Options.
The field ‘transporterCode’ can contain a new value: ‘BUDBEE’. Related to the new ‘transporterCode’ ‘BUDBEE’ the response will contain new shipping label offer ID’s.

For more information, please refer to the API documentation here: https://api.bol.com/retailer/public/Retailer-API/v7/functional/retailer-api/verzenden-via-bol.html

From 09:50 until 10:00 our Retailer API was down. You might have noticed a lot of 50x's responses. Apologies for the inconvenience.

Please check your responses and process status (if available) to check whether your requests were processed successfully.

Tomorrow between 05:30 and 07:30 AM you can experience time-outs on PUT requests related to confirmations of shipments and cancellations.

We intend to queue all requests and process them all, so the time-out can be ignored. Please monitor this post for updates

Update 13-07-2022: The downtime is planned for tomorrow morning 14-07-2022

Tuesday the 5th of July between 6:00 AM and 07:00 AM a downstream application will have some downtime.

This will mean that:

- GET offer requests will fail

- Offer exports will not be generated

- Offer information will be missing in GET single order requests

- Offer creates/deletes/updates will be delayed (please check the process status)

GET offer requests result in a 50x-error

This resulted in missing offer information in GET single order requests as well

The issue started 15:45 and ended 16:30

Budbee has been added as a new transporter in the Returns API flow. Now onwards, while retrieving the details of a return through the Get a return by return id endpoint, Budbee is returned as a string value for transporterName field in the response, in addition to the already known transporters such as PostNL or DHL.

Note: The transporter is always selected by bol.com and this change only impacts the information you receive through the GET endpoint.

Since 09:30 we experience some delay on our offer endpoints.

Therefore it could be possible that some creates, updates or deletes have some delay with publishing. Time-outs did not happen yet, but can be expected to happen

Update 11:00

Everything is back to normal. The delays did not result in time-outs

Since 10:00 we experience a issue with offer endpoints.

Therefore all offer calls will have some delay for publishing on our website.
It is also possible that your offer call end up in a failure, we advise you to double check the process-status.

Update 11:15

Everything is back to normal

Since 11:30 we experience some delay on our offer endpoints.

Therefore it could be possible that some creates, updates or deletes have some delay with publishing.

Update 12:40:

Alot of offer changes also end up in a failure, please double check the process-status.
We are still working on a solution.

Update 13:30:

Also the confirmation orders of shipment and cancel are affected, it could be possible that orders and offer calls end up in a failure, be sure to double check the process-status.

Update 14:40:

Everything is back to normal

On Wednesday 01-06-2022 between 06:00 and 06:25 there will be a planned downtime for the GET endpoints for orders and returns. Therefore you are not able to receive these data.

After 06:25 everything will be back to normal

Earlier this morning between 05:30 and 07:10 we experienced downtime.

Please check whether your requests were processed succesfully. (by checking the process-status)

Apologies for the inconvenience.

Update 09:30:

Because of this downtime almost all offer calls end up in a time out, after 07:10 we had a delay of processing the offer calls till 09:30. Since then everything is back to normal.

Currently the insights endpoint is unavailable. We are working on a fix and will keep you updated

Update: Since 07:30 the issue has been resolved

Wednesday 25th of May our API will be unavailable for a few minutes somewhere between 6:00 and 07:00

Tuesday 31st of May between 06:00 and 06:20 it will not be possible to send us offer updates (stock price deliverycode) and retrieve offer exports.

If there are any updates related to this downtime, we will update this post

Apologies for the inconvenience

Update 24-05:

The downtime for tomorrow is cancelled, we will let you know in a separated attention when this downtime take place.

Since 12:00 it could be possible you did not get offer information in the retailer api. The endpoint that are effective are GET offer ( all versions) and GET order v5 ( v6 and v7 are fine)

Update 12:30:
This issue is resolved

There is an issue with retrieving delivery options and creating shipping labels in our API.

We are investigating and will update you as soon as it is fixed

Apologies for the inconvenience

Update: Since 17:35 the issue has been fixed

Since today we experience some issues with the code flow. After the login page for a new connection you receive a error: "Er is een probleem: vanwege een technische storing kan deze niet worden uitgevoerd"

We are working on a solution.

Update 15:30: issue is resolved

Orders retrieved via the API v6/v7 can include an inaccurate latestdeliverydate or exactdeliverydate.

This issue was discovered yesterday and fixed this morning at 09:20.

For v6 users : this issue has been going on from 26-4 until this morning

For v7 users: this issue has been going on from 6-4 until this morning

For new orders since 09:20 the date is accurately exposed in the API

The fix did not correct the deliverydate for the involved orders, the information in the selling account is correct

As communicated before, our API version v4 has been switched off. For migration guides, please check our developer website: https://api.bol.com/retailer/public/Retailer-API/index.html

If you did not migrate in time, you can temporally work via your Selling acccount

We are investigating outage on the Retailer API with the highest priority

This is going on since 17:35

Update 18:20: Everything is back to normal

Since 15:00 we experience some delay on our offer endpoints.

Therefore it could be possible that some creates, updates or deletes have some delay with publishing.

16:30: Everything is back to normal.

As communicated earlier, the API V4 will be switched off on the 1st of May 2022, however, due the 1st of May being in the weekend, it’s decided the API V4 will be officially switched off on Monday the 2nd of May!

Still need to migrate? What is expected of you now?
You can arrange the migration yourself or have it done with the help of an integration partner. Are you already using 1 of our integration partners? Then you will automatically migrate to API V5 or V6 or V7. Please check this with your integration partner to be sure. If you have your own IT team or developer, please arrange the migration according to the below-stated migration guides.

The API V4 will continue to work for only 3 more weeks; you have until May 1, 2022 to migrate. Do this in time, so that your processes continue to work properly after this date. Take into account the IT time needed to migrate. Migrating can take up to a few weeks, depending on your integration and IT skills.

Use the following migration guides to make a smooth transition if you arrange the migration yourself:

Migration guide for V4 to V7

Migration guide for V4 to V6

Planning next versions
On this release planning page, you can read more about when an API version becomes available and when a version is removed. Keep a close eye on this planning, so that you know when you need to switch to the next API version.

A new version of the Retailer API has been released on 1st April 2022.

The Retailer API version 7 introduces some significant improvements in the API structure.

The resources are logically grouped and the API has been separated into three key subjects:

• Advertising API - containing advertising specific API endpoints.
• Retailer API - containing retailer specific API endpoints.
• Shared API - containing endpoints that are shared between both advertising and retailing.

New features:

• Advertising – Moved from BETA to General Availability in the v7. Allows you to manage sponsored product advertising campaigns that are promoted on the bol.com webshop. For more information on the Advertising API, refer to the functional documentation.
• Promotions – Moved from BETA to General Availability in the v7. Allows you to view all the current and upcoming retailer specific promotions and the promotions belonging to a specific bol.com campaign. To know more about the Promotions API, refer to the functional documentation. For more information on Promotions in general, click here (in Dutch).

Improvements:

• Product Content - v7 offers significant improvements on providing feedback on the uploaded product content. Compared to earlier versions of the API that provided only top level validation, v7 now offers you specific per attribute/image end-state feedback with up to 28 days of upload history. It provides you comprehensive feedback on the upload status such as, which content was successfully published, which content was declined for technical reasons/errors or when the content from other sellers was selected. These insights provide more clarity and enable you to deliver less duplicate content, fix the validation errors per product, update your product content, and create other follow-up actions.
  Additionally, the process to create product families has also been enhanced slightly. To accommodate these changes, v7 onwards uploading the content for multiple products has now been changed to a single product. For more information on the Product Content API, refer to the functional documentation.
• Offers Subscription - A new subscription event, Offers, has been added to the Subscriptions API which allows you to receive notifications about the status of a created offer. For more information on the Offers Subscription, refer to the functional documentation.
• Other improvements include changes in the functional documentation.

For more information, refer to the v7 Release Notes.

As per April 25th new assortment of products containing a CE-mark (such as toys and electronic products) are mandatory to upload a photo of the CE-mark on the product, on the packaging or on an accompanying document. CE-marks are very important for our customers to verify the safety of products and are mandatory according to European legislation in some product groups.

You can check which products/chunks are in scope in our data model. The documents can be uploaded in the same way as other documents like Manuals or Energy labels (PDF).

As communicated earlier, the API V4 will be switched off on the 1st of May 2022, so it is important to migrate in time. Now is the right time to switch to the API V7. Switching to the V5/6 is also possible, however, the V5/6 will exist for a shorter period of time than the V7. Therefore, we advise you to immediately switch to the V7. The API V7 not only offers you new features – you are also immediately ready for the future! We are happy to provide you with more information about this.

What is expected of you now?
You can arrange the migration yourself or have it done with the help of an integration partner. Are you already using 1 of our integration partners? Then you will automatically migrate to API V5 or V6 or V7. Please check this with your integration partner to be sure. If you have your own IT team or developer, please arrange the migration according to the below-stated migration guides.

The API V4 will continue to work for only 3 more weeks; you have until May 1, 2022 to migrate. Do this in time, so that your processes continue to work properly after this date. Take into account the IT time needed to migrate. Migrating can take up to a few weeks, depending on your integration and IT skills.

Use the following migration guides to make a smooth transition if you arrange the migration yourself:

Migration guide for V4 to V7

Migration guide for V4 to V6

Planning next versions
On this release planning page, you can read more about when an API version becomes available and when a version is removed. Keep a close eye on this planning, so that you know when you need to switch to the next API version.

Between 15:45 and 16:30 we experience some timeouts on all offer endpoints.

Therefore double check all the process-status of the offer calls

Our apologies

Yesterday we came across a longer-lasting issue. (since 15-3)

Recreating an offer through the API after deleting an offer or your whole assortment in the Seller Account resulted in the offer not created, even though a process-status SUCCESS is returned.

We are still investigating the exact impact but it has been solved since yesterday 10:25

We are happy to announce that the Advertising API is officially in the Open Beta phase. The Advertising API allows you to manage sponsored product advertising campaigns that are promoted on bol.com. You can create campaigns and all their underlying objects. Additionally, you can extract detailed reports to refine your advertising strategy and optimize your sales potential.

Want to know more about the technical insides of the API, take a look at the API documentation

Want to join in on the Open Beta phase or some more information about the API? Fill in this form

There are issues with our Retailer API. Some requests may end up in a time-out or 500/504 error. We are investigating the issue and will keep you updated in this post.

Update 13:00: The issue has been fixed. An occasional 500 could still happen, but please contact us when you get 504 Timeouts in response

Dear Partners,

Hereby a reminder about our Content FTPS phase out.

This messaged is aimed at partner using Content FTPS. If you are not using Content FTPS this message does not apply to you.

After 01-04-2022 we stop allowing textual content and images to be delivered via FTPS.

Before this date all current users of Content FTPS need to migrate to alternatives:

Retailer API

More than a year ago we made it possible to deliver content via Retailer API, and by now the vast majority of former FTP users has switched to this new channel. The content module of the Retailer API will be updated with our newest futures.

More information about Retailer API (Dutch)

Pros: Complete solution: can also be used for prices and orders, includes all future services.

Cons: You need to develop the API connection, needs to be upgraded every 1,5 years

Interesting when: having +2500 products, already using Retailer API for prices and orders

Integrator

We have selected multiple integrators which can be used for automation. Integrators have established and reliable connections with bol.com, which can be used for a monthly fee.

More information about integrators (Dutch)

Pros: Complete solution: can also be used for prices and orders. You do not need to build your own Retailer API connection. The integrator will upgrade you connection every 1,5 years.

Cons: Monthly fee. You still need to create a mapping to match your content with our datamodel.

Interesting when: having +2500 products, no inhouse IT knowledge.

Verkoopaccount (Selleraccount)

The verkoopaccount is our portal in which all aspects of selling on bol.com can be managed. It is possible to upload / change up to 2500 products at a time in our Verkoopaccount. It is possible to give employees access to separate parts of the seller account, for example: only adding products and content.

More information about adding multiple articles in verkoopaccount (Dutch)

Pros: Free and easy to use

Cons: No automation possible. Limited to editing 2500 products at a time

Interesting when: <2500 products, if you do not want to make costs.

Since 15:00 we experience some problems with offer endpoints, therefore it could be possible that offer updates and creates end up in a timeout.

We advise you to check the process-status so you can see what the status is of the call.

Update 15:40:

Everything is back to normal

Since 15:00 there is issue with GET offer, therefore it could be possible that it end up in a 500 error.

We will update this notification when it is fixed

Update 18:00: Issue is been resolved

Since this morning a delay can be experienced in the Offer Exports service / Unpublished Offers Exports.

We are investigating the issue and will give an update in this channel when the delay is fixed.

Since 15:45 we experience some problems with offer endpoints, therefore it could be possible that offer updates and creates end up in a timeout.

We advise you to check the process-status so you can see what the status is of the call.

Update 16:45:

Issue is resolved

We are investigating an issue related to POST/Offers requests. A lot of requests end up in a time-out. The issue seems to have started yesterday around 14:00

Update 14:03 The issue has been fixed, please retry the failed requests.

As of today, the conceptual migration guide for API v7 is available. This guide is intended to be an indication of the changes that will be available in v7. It is not comprehensive and is subject to change with the release. Version specific functional documentation and Redoc links pointing to the APIs and its endpoints will be available after the v7 (GA) release. This release is set for April 1st, 2022.

Please check the migration guide here: https://api.bol.com/retailer/public/Retailer-API/v7/migrationguide/v4-v7/migrationguide.html

Starting 07 March we updated the Terms of Service of the Retailer API.

Changes:

• Added context, definitions and usage of our new Advertising endpoints
• Updated the usage limitations of the Retailer API to be broader than just processing orders

Click here to read the updated Terms of Service of the Retailer API (in Dutch only)

We will change the available sorting methods. As of the 31st of March only the following sorting methods will be available. The other sorting methods will be deprecated.

rankdesc - Sort on sales ranking descending

priceasc - Sort on price ascending

pricedesc - Sort on price descending

datedesc - Sort on publishing date descending

ratingdesc - Sort on rating descending

For the old, to be deprecated, sorting methods, please consult: LINK

Because of a internal downtime transporter information will not be available in the GET shipment endpoints on 03-03-2022 between 08:00 and 08:18.

After 08:15 everything will be available

As of today (1 March 2020) you can send documents of products containing a CE-mark. CE-marks are very important for our customers to verify the safety of products, and are mandatory according to European legislation in some product groups.

You can check which products/chunks are applicable in our data model. The documents can be sent in the same way as other documents like Manuals or Energy labels (PDF)

Since 21-12-2021 16:00 the Search term endpoint is down for al version.
The response that you will received after a call is that this endpoint is in a closed beta, but the whole endpoint is not available.

Because the issue is quite big, we will assume this will not be fixed this week.

Our apologies for this, we will update this message when it is fixed.

Update 24-12:
Issue solved.

Since 12:00 we are facing an issue where the Create Offer Export could take longer to process, or can be end up in a timeout.

We are working on it.

03-12-2021 14:15: Everything is back to normal.

Since 11:00 we are facing an issue where the Create Offer Export could take longer to process, or can be end up in a timeout.

We are working on it.

02-12-2021 12:30: Everything is back to normal.

Since 10:30 we are facing an issue where the Create Offer Export could take longer to process, or can be end up in a timeout.

We are working on it.

29-11-2021 12:30: Everything is back to normal.

Since 09:00 we experience some issues with GET order by orderid endpoint.
Therefore it could be that you receive an order without billingdetails in the response.

We are working on it.

Since approximately 11:45 this morning we are having some issues with the GET validation report. We are working on it.

Update 23-11 14:15:

Issue solved

Currently, we are facing an issue where the Create Offer Export could take longer to process. We are working on it.

Update 22-11 14:15

The issue seemed to be solved. Had any failing requests? Please retry your request.

Since 10-01 could it be possible that you received a SUCCES in the process status id but is not processed.
The offerid that you received is the same offerid that has been deleted. Therefore the offer is not processed and is not online.

The same issue is also in the seller dashboard, there is not any workaround.

We are working on it.

10-01-2022 23:00: The issue is been fixed, we advise you to check the process status from offer updates to double check if the offer is online.

Since 19-1 a delay can be experienced in the creation of Offer Exports and Unpublished Offers Exports

The delay is around 50 minutes. We are investigating the issue and will give an update when the delay is fixed.

19-01-2022 13:00: The issue has been fixed, the service is working as intended again

Since 20-1 a delay can be experienced in the creation of Offer Exports and Unpublished Offers Exports

We are investigating the issue and will give an update when the delay is fixed.

20-01-2022 13:45 The issue has been fixed, the service is working as intended again

Since 4-2 there is an issue related to the deleting of Offers. The requests can result in a time-out.

We are investigating the issue.

04-02-2022 14:50 The issue has been fixed, the service is working as intended again

Recently we found out that our validation on product image restrictions didn’t check for the minimum dimensions. This week we’ve fixed that.

Product images have to have a minimum of 500x500 pixels, which we now enforce.

If your images don’t comply, you will receive feedback that your file’s resolution is too low (min 500 x 500 pixels).

If you’ll see an increase in error messages regarding images, this might be the cause and we urge you to check the dimensions of product images you send.

Since this morning it could be possible that you receive the error message: Jwt issuer is not configured when doing any call on our open api with the JWT token.

We are working on a solution

Since 10:00 there is some issue with receiving offer information. The recourses where we can not give offer information is:

- offer; the GET offer by offerid endpoint will be empty

- orders; the offer information will not be available in the order information for example ean, offerid and internal reference.

- replenishment; unable to provide a replenishment

We are working on a solution

Update 10:45: all offer endpoint are effective and it is slowing down or end up in a timeout

Update 11:15: This issue is resolved

Since 11:00 is there some outage in the open API. The Search en list endpoints will end up in the error "Unable to perform search operation"

We are working on a solution

Update 14:00: issue is resolved

Since 11:00 you can experienced a delay in the creation of Offer Exports and Unpublished Offers Exports or some will end up in a timeout

We are investigating the issue and will give an update when the delay is fixed.

Update 13:00: Everything is back to normal

Between 14:15 and 14:50 all offer update calls ended up in timeouts, therefore all these updates were not processed.

Double check the process-status for these calls and if this update is timed out you can retry the call

Pickup points with Verzenden via bol.com

The bol.com Retailer API is ready to offer our partners the ability to use delivery pickup points via DHL in the Netherlands, and in Belgium.

We will automatically offer this option to customers in their buy block as a free option if their product is eligible for pickup points. This will become automatically available in the API end of March 2022. For more information, see this topic.

What do you need to do?

As a partner with "Verzenden via bol.com" you do not need to do anything extra to enable this option, and the process works much the same as other shipment types. If a customer has selected a pickup point during the order, in the [Get single order] call field will be "true", and the [shipmentDetails.pickupPointName] field will have the name of the collection location. Then when you fetch [shipment data], the same fields will appear from the order that were added to the GET single order call.

Shipping labels

We have defined a set of templates for shipping labels for each specific pickup point type. When you generate a shipping label with pickup points, it will automatically display the correct destination and customer details.

Customers can also choose to deliver their packages in the evening.

This is an option that will automatically appear in their checkout if it is available for the items. You can see if an order item has an evening delivery selected if the [timeFrameType] field value is "EVENING". In that case you will only be able to choose an evening shipping label and you cannot mix labels with other order items. We only offer evening shipments for parcels, so if the item would fit a mailbox, you should adjust the packing dimensions.

For more information including the required dimensions for packages, see Evening deliveries with Verzenden via bol.com.

Since Wednesday 02-02-2022 it could be possible that the process status for a handle return call end up in a failure with the message : “connection reset”

If you receive this error message you can retry the same call directly till it end up in a SUCCES, there is nothing further you need to change about the call.

For all return calls we advise you to double check the process statuses since Wednesday.

Dear Partners,

This messaged is aimed at partner using Content FTPS. If you are not using Content FTPS this message does not apply to you.

After 01-04-2022 we stop allowing textual content and images to be delivered via FTPS.

Before this date all current users of Content FTPS need to migrate to alternatives.

After 01-04-2022 content send via the FTP will not be accepted.

Key reasons for this decision:

• Small usergroup: only 200 partners are still using Content FTPS
• Users switched to API: 90% of our automated partners switched from FTP to Retailer API last year.
• Future services: we are not able to offer all our (future) services via FTPS.
• Focus on API: we focus on the Retailer API as the place for automating content delivery.

We hope this decision finds you well and expect that the date of 01-04-2022 will grant you enough time to switch to one of our alternatives:

Retailer API

More than a year ago we made it possible to deliver content via Retailer API, and by now the vast majority of former FTP users has switched to this new channel. The content module of the Retailer API will be updated with our newest futures.

More information about Retailer API (Dutch)

Pros: Complete solution: can also be used for prices and orders, includes all future services.

Cons: You need to develop the API connection, needs to be upgraded every 1,5 years

Interesting when: having +2500 products, already using Retailer API for prices and orders

Integrator

We have selected multiple integrators which can be used for automation. Integrators have established and reliable connections with bol.com, which can be used for a monthly fee.

More information about integrators (Dutch)

Pros: Complete solution: can also be used for prices and orders. You do not need to build your own Retailer API connection. The integrator will upgrade you connection every 1,5 years.

Cons: Monthly fee. You still need to create a mapping to match your content with our datamodel.

Interesting when: having +2500 products, no inhouse IT knowledge.

Verkoopaccount (Selleraccount)

The verkoopaccount is our portal in which all aspects of selling on bol.com can be managed. It is possible to upload / change up to 2500 products at a time in our Verkoopaccount. It is possible to give employees access to separate parts of the seller account, for example: only adding products and content.

More information about adding multiple articles in verkoopaccount (Dutch)

Pros: Free and easy to use

Cons: No automation possible. Limited to editing 2500 products at a time

Interesting when: <2500 products, if you do not want to make costs.

The API V4 will be switched off on the 1st of May 2022, so it is important to migrate in time. Now is the right time to switch to the API V6. Switching to the V5 is also possible, however, the V5 will exist for a shorter period of time than the V6. Therefore, we advise you to immediately switch to the V6. The API V6 not only offers you new features – you are also immediately ready for the future! We are happy to provide you with more information about this.

What is expected of you now?
You can arrange the migration yourself or have it done with the help of an integration partner. Are you already using 1 of our integration partners? Then you will automatically migrate to API V5 or V6. Please check this with your integration partner to be sure. If you have your own IT team or developer, please arrange the migration according to the below-stated migration guides.

The API V4 will continue to work for a few more months; you have until May 1, 2022 to migrate. Do this in time, so that your processes continue to work properly after this date. Take into account the IT time needed to migrate. Migrating can take up to a few weeks, depending on your integration and IT skills.

Use the following migration guides to make a smooth transition if you arrange the migration yourself:
Migration guide for V4 to V6
Migration guide for V4 to V5

How do I know which API version I’m using?
In the ‘Accept header’ of your API requests, you can see which API version you are using. Is it not possible to see this yourself? Then ask your developer or integration partner which API version you are currently using.

What are the benefits of the Retailer API V6?
The Retailer API V6 contains the following new functionalities:

• Subscription API for process status and shipment events. For more information see Subscriptions.
• Image labeling for product content. For more information see image labeling.
• Transport events for shipments. For more information see monitoring a shipment.

Planning next versions
On this release planning page, you can read more about when an API version becomes available and when a version is removed. Keep a close eye on this planning, so that you know when you need to switch to the next API version.