Campaigns

The Campaigns API helps to you to create and manage your campaigns efficiently through the following endpoints:

Create a campaign - Create one or multiple campaigns.
Update a campaign - Updates one or multiple campaigns.
Get a list of campaigns - Retrieves a list of campaigns in a paginated format.

Advertising campaign hierarchy

At the top level, a campaign holds some basic attributes such as the name, start date, budget, daily limit and campaign type.

Every campaign will have its own campaignId which will be inherited by its set of ad groups. Each ad group will also have its own adGroupId, which will be inherited by its set of ads, keywords, negative keywords, target categories and _negative target categories, depending on the campaign type 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.

Create campaigns

The following scenarios will walk you through the steps to create firstly an automatic, then a manual campaign.

Create an automatic campaign

To create a basic campaign with automatic keyword targeting and automatic bidding, you will need to do three calls to the API:

Create an automatic campaign
Create one ad group underneath the new campaign
Create one or more ads underneath the new ad group.

Create the campaign

Create a campaign

You can set the fields as you wish, but the campaignType should be AUTO. This will provide you with a set of organically-derived keywords related to your product, and a bidding strategy where bol will try to target your bids at the acosTargetPercentage.

Maximum amount of non archived campaigns is 15.000.

For example, if your acosTargetPercentage is "10", the bidding will target towards spending 10% of the product revenue on advertising sponsorship in this campaign.

Automatic campaign example

{
  "campaigns": [
    {
      "name": "My first automatic campaign",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "dailyBudget": {
        "amount": 100,
        "currency": "EUR"
      },
      "totalBudget": {
        "amount": 1500,
        "currency": "EUR"
      },
      "targetCountries": [
        "NL",
        "BE"
      ],
      "targetChannels": [
        "DESKTOP",
        "MOBILE",
        "TABLET",
        "APP"
      ],
      "campaignType": "AUTO",
      "acosTargetPercentage": 10,
      "state": "ENABLED"
    }
  ]
}

Both the dailyBudget and the totalBudget are optional.

The response will contain among other things the new campaignId which you can use to create ad groups.

Create an ad group under the campaign

Create an ad group

Ad groups hold groups of products that will be targeted using the strategies defined in the campaign, as well as keywords, negative keywords, target categories and negative target categories. For example, a campaign might consist of a range of electronics products, but you might want to use separate ad groups for "smartphones" versus "chargers". This will allow you to monitor the performance of the different product types in your assortment.

When creating an ad group, you should also use the campaignId which you received above. The process status response from this call will contain the new adGroupId which you will use to create target products.

Create ads under the ad group

Create an ad

You can now add your specific products that you want to target with the campaign. Each product takes the adGroupId from the previous call, as well as the product EAN. Depending on the campaignType you set on the parent campaign, you can also set a bid.

The process status response will contain the adId for the ad that you created.

At this point your sponsored product campaign is active and will run and promote your products on bol. You can verify it using the GET endpoints:

Get a list of campaigns - Retrieves a list of campaigns in a paginated format.
Get a list of ad groups - Retrieves a list of ad groups.
Get a list of ads - Retrieves a list of all ads within an ad group in a paginated format.

Create a manual campaign

Manual campaigns will require you to supply your own keywords once you have created the campaign.

Start by creating the campaign, using campaignType=MANUAL:

Create manual targeting campaign example

{
  "campaigns": [
    {
      "name": "My first manual campaign",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "dailyBudget": {
        "amount": 100,
        "currency": "EUR"
      },
      "totalBudget": {
        "amount": 1500,
        "currency": "EUR"
      },
      "targetCountries": [
        "NL",
        "BE"
      ],
      "targetChannels": [
        "DESKTOP",
        "MOBILE",
        "TABLET",
        "APP"
      ],
      "campaignType": "MANUAL",
      "state": "ENABLED",
      "constraints": []
    }
  ]
}

Following this you should create ad groups and ads.
Then you can create your sets of products, keywords, negative keywords, target categories and negative target categories.

Create keywords for a manual campaign

Create a keyword

Keywords are the words and phrases that are used to match a webshop query with an advertisement. To create keywords, you need to supply the adgroupId, the matchType, and the keyword text, for a single keyword.

Create a campaign with manual bidding

If you want to create your own bidding strategy for either keywords or target categories, you will need to create a campaign with the same steps as before, but with the difference that you should set your bidding strategy to one of the above values. In this case, you will supply the bids per keyword or target category yourself.

Manual bidding by keyword campaign example

{
  "keywords": [
    {
      "adGroupId": "12345",
      "state": "ENABLED",
      "keywordText": "keyword",
      "matchType": "EXACT",
      "bid": {
        "amount": 0.5,
        "currency": "EUR"
      }
    }
  ]
}

In your keywords or categories, you can set the individual bid value for each item.

Update campaigns

You can change a running campaign at any time, to optimize your advertising strategy or change your ad spend. Use the various PUT endpoints to modify the components of your campaign. The PUT action requires you to provide the full JSON structure, only fields that have changed will be updated.

PUT campaign example

{
  "campaigns": [
    {
      "name": "My first automatic campaign",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "dailyBudget": {
        "amount": 100,
        "currency": "EUR"
      },
      "totalBudget": {
        "amount": 1500,
        "currency": "EUR"
      },
      "targetCountries": [
        "NL",
        "BE"
      ],
      "targetChannels": [
        "DESKTOP",
        "MOBILE",
        "TABLET",
        "APP"
      ],
      "campaignType": "AUTO",
      "acosTargetPercentage": 10,
      "state": "PAUSED",
      "constraints": []
    }
  ]
}

You cannot change the campaign type of a campaign for reporting purposes. You can create another campaign with the other targeting type and move ads, keywords and/or categories to that.

Pausing and archiving

If a campaign is paused, it immediately stops showing ads and spending money. However, the underlying ad groups, keywords, and target products remain untouched. A paused campaign can be re-enabled at any moment by setting the state back to ENABLED.

If a campaign is archived, it is similar to a deleting it except that this operation cannot be undone and the archived campaign will not be visible in the Get a list of campaigns endpoint.

The archived campaigns and ad groups are not actually deleted from the database. They will still appear in the reporting endpoints if they have generated activity in the requested period. The underlying ad groups, keywords, and ads will remain untouched but cannot be used to run ads as a result of archiving.

The following objects in a campaign can also be paused or archived, and this logically will affect their underlying objects in the same way:

Campaigns
Ad groups
Ads
Keywords
Negative keywords
Target categories
Negative target categories

For example, if an ad group is archived, all of its products, keywords, and negative keywords will also become unusable.

Similarly, ad groups can be archived but not fully deleted.

Changing ad groups, ads, keywords and target categories

On top of changing the state, you can make the following changes to your campaign objects:

Change the bid value for any ad, keyword and/or target category.
Add ads, keywords and/or target categories to an ad group through the Create an ad, Create a keyword, Create a negative keyword, Create a target category, and Create a negative target category endpoints.

Deleting negative keywords and negative target categories

Delete a negative keyword by keyword id - Deletes a negative keyword.
Delete a negative target category by keyword id - Deletes a negative target category.

Negative keywords and negative target categories allow proper deletion through their respective DELETE endpoints. Supply the keywordId or categoryId and delete them one by one (or in bulk). To find the relevant IDs, you can use Get a list of negative keywords and Get a list of negative target categories.

Negative keywords

Get a list of negative keywords - Retrieves a list of negative keywords for a specific ad group in a paginated format.
Create a negative keyword - Creates a new negative keyword and adds it to the ad group.
Delete a negative keyword by keyword id - Deletes a negative keyword.

Negative keywords and/or negative target categories can be used to prevent undesirable matches on your campaign. If a negative keyword is part of the search terms of the cons

Retrieving campaigns

Use the endpoint Get a list of campaigns - Retrieves a list of campaigns in a paginated format.

Use the campaignIds on the request body, as a filter to list only specific campaigns. If campaignIds is not given, all campaigns of the advertiser will be returned as paginated.

Besides campaignIds, pagination options can be given on request body as page and pageSize.

It is not mandatory to fill in either the campaignIds or the page or pageSize, or all.
There is an upper limit on the campaignIds and pageSize, which is 50 for each request.

list campaigns endpoint response body example

{
  "campaigns": [
    {
      "campaignId": "1000000000000001",
      "name": "My first automatic campaign",
      "state": "ENABLED",
      "source": "REGULAR",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "dailyBudget": {
        "amount": 100,
        "currency": "EUR"
      },
      "totalBudget": {
        "amount": 1500,
        "currency": "EUR"
      },
      "targetCountries": [
        "NL",
        "BE"
      ],
      "targetChannels": [
        "DESKTOP",
        "MOBILE",
        "TABLET",
        "APP"
      ],
      "campaignType": "AUTO",
      "acosTargetPercentage": 10,
      "state": "ENABLED",
      "constraints": [
        "OUT_OF_DAILY_BUDGET",
        "OUT_OF_TOTAL_BUDGET"
      ],
      "campaignConstraints": [
        {
          "reason": "OUT_OF_DAILY_BUDGET",
          "creationDateTime": "2024-01-13T13:16:03.892616+02:00"
        },
        {
          "reason": "OUT_OF_TOTAL_BUDGET",
          "creationDateTime": "2024-01-16T15:01:08.098715+02:00"
        }
      ]
    }
  ]
}

Retrieved campaigns might have constraints applied. Constraints serve as a means of indicating what campaign-level restrictions apply (if any). The presence of a constraint indicates that the campaign is currently not running. We distinguish between the following campaign-level constraints:

OUT_OF_TOTAL_BUDGET - Campaign budget is fully spent
OUT_OF_DAILY_BUDGET - Daily budget is fully spent
PENDING_START_DATE - Campaign start date is in the future
ENDED - Campaign end date has passed