Advertising API

This feature is being released in closed beta for v7. For now, only the reporting endpoints are available. The remaining features will be rolled out when development is ready.

The Advertising API allows you to manage sponsored product ad canpaigbs that are promoted on the bol.com webshop. This first release consists of a set of reporting endpoints to provide you with insights into the performance of your sponsored product ads on various levels. You can then use this information to further optimize your ad spend and targeting.

Advertising campaigns overview

To understand the core concepts of advertising at bol.com, refer to the articles at Advertising via bol.com (Dutch). If the sponsored products in your campaign win the bidding process, they will be promoted to the top of the search results for their product type. This can significantly improve their sales potential.

For more information see the following topics:

Authorization

Authorization for the Advertising API uses the same method of authentication as the standard intermediary authorization flow. You can request a JWT token through the same means as the Retailer API, but you should specify that the scope of the token should include Advertising. The token you receive back will allow you to access the Advertising endpoints.

Asynchronous request handling

The Advertising API uses the same standards as the other endpoints in the Retailer API when it comes to handling data manipulation requests. This means that all PU, POST, and DELETE requests will be handled asynchronously, via the v7/functional/process-status.adoc. The initial call will return a process status event ID, which you can use to retrieve the status from the process status endpoint.

Advertising campaign anatomy

At the top level, a campaign holds some basic attributes such as the name, start date, budgets, and bidding strategy. Once your campaign has been created, you can then add ad groups to hold sets of targeted products and keywords.

Thus, every campaign will have its own campaign-id which will be inherited by its set of ad groups. Each ad group will also have its own ad-group-id, which will be inherited by its set of targeted products and keywords, depending on the bidding strategy that was set on a campaign level. When creating and editing elements within a campaign, it is important to understand the hierarchy between these objects, so that you do not accidentally change a child object when making changes to a parent object such as a campaign or an ad group.

Campaign anatomy

Reporting on advertising performance

The reporting endpoints are a crucial resource to help you improve your advertising campaign performance by analyzing and refining your keywords, products, and bids. You can see the performance data related to your impressions, clicks, conversion rates, sales, spends, and other factors over a given period.

We provide separate reporting endpoints for all levels of an advertising campaign, as well as a report that aggregates all campaigns for an advertiser. Each report contains object-specific results which can be found in the ReDoc.

You need to supply the date range and the ID of the advertiser, campaign, or ad group, depending on the level of report that you are retrieving. You will get back the aggregated performance metrics of that object for the period. Refer to the ReDoc descriptions for more information about the fields you receive back from these endpoints.

Reporting date ranges

Each reporting endpoint requires you to enter a date range. You are limited to 7-day ranges for every report, and the last full day shown on the report will be the last day prior to the end-date on which there was at least one ad impression.

If an ad received no impressions on a day within the defined date range, that day will not be part of the report. You can analyze the date range performance for all days, taking the missing days as having no results.

When reporting on actual sales and conversions, the report will take into account an attribution period of 14 days after the visitor viewed the advertisement. This is to allow time for the visitor to make the decision to purchase after being influenced by the ad.

Example 1. Date range example

If you request a campaign performance report with a date range of "2021-09-01" to "2021-09-08", the date of the last result will be "2021-09-07", assuming they had impressions on that day. If during that period a visitor saw the sponsored product on 2021-09-06 and then purchased it on 2021-09-20, that item will be included in the sales and conversions totals.

Sales and conversions to different EANs

Several reporting endpoints include the fields salesOtherEan and conversionsOtherEan. These fields show sales of similar products within your own product portfolio after a visitor viewed an ad. They will not show sales of competitors. If a visitor viewed one of your ads for a blue iPhone 13, then purchased a red iPhone 12 from you, it will be included as another EAN.

Keyword performance

The keyword performance report contains the performance of all keywords in your ad group, and includes the averageWinningBid field which shows the average value of the winning bid for that keyword. The number is averaged across the days contained in the specified date range and will therefore be the same for all days returned.

Search terms performance

The search terms performance report is similar to the keyword performance report, but instead of showing the advertiser’s keywords, it shows the search terms entered by customers that triggered the keywords, including views for which there were no keywords.

This can provide insight into the search terms customers are using to find your products, so that you can refine your own keywords and use them to create manual keyword campaigns. It can also be helpful to create negative keywords to prevent undesirable matches with your products.

If a search term did not contain keywords, this indicates that it was part of an automatic targeting campaign. In this case the keywordText field will show N/A.

Example 2. Search terms example

If you have the term "iphone" in your keywords, this might lead to a lot of impressions, but you might want to know what the complete search terms were for the impressions, such as "iphone 12 black", "iphone 11 case", "iphone charging cable", etc. You might also see that you received a large number of impressions on ads that used terms you had not included, and you can include these in your ad group.