Campaigns¶

A Campaign is a group of ads, sharing a campaign budget. With campaigns, it is possible to control spending for this entire list of ads and, in one go, start/stop advertising with the entire list of (active) ads. Campaigns can have their own budgets, both daily and total. If these are not set, the total budget will automatically be set to “UNLIMITED” and the daily budget will be set to a default value.

For the time being, we only allow multiple campaigns for sellers of Kleinanzeigen. This means for all other markets, we allow only 1 campaign per seller, effectively grouping _all_ the ads in that one campaign. To make transitions to use campaigns easier, we will ensure that each (new or existing) seller already has a campaign, and if the seller has ads, these will be part of the campaign.

The first campaign to be created, either explicitly or by us ensuring there is one, will also become the default campaign. This means that whenever ads are created through API without specifying a campaign Id, the ad will become part of this default campaign. For markets where only one campaign per seller is allowed at the moment, this campaign is also the default.

You can get your campaign by calling GET /campaigns or GET /campaign/{id}. Campaign budgets can be modified by using PUT /campaign/{id}/budgets, and controlling campaign status can be done by PUT /campaign/{id}/status/{status}. We expect to add more campaign functionality in the future.

Fields¶

Field	Type	Constraints	Mandatory	Writable
id	integer	positive,readonly	–	no
status	string	enum	yes	yes
dateCreated	string	readonly	–	no
datLastUpdated	string	readonly	–	no
vendorId	string	readonly once set	no	only once
title	string	max 64 chars	no	yes
isDefault	bool	–	no	no
budgets	[]Budget	readonly	yes	yes
budgets.daily	object	see below	yes	yes
budgets.total	object	see below	yes	yes
budgets.daily.limitMicros	string	see below	yes	yes
budgets.daily.spentMicros	string	see below	no	no
budgets.total.limitMicros	string	see below	yes	yes
budgets.total.spentMicros	string	see below	no	no

id¶

Unique reference to the campaign, needs to be omitted in a POST action. One of Campaign Status

status¶

The status of the campaign, one of Campaign Status.

dateCreated¶

The ISO 8601 UTC date and time the campaign was created.

datLastUpdated¶

The ISO 8601 UTC date and time the campaign was last updated.

vendorId¶

Any non-empty string with a maximum length of 64 characters. Should be unique per customer. Can either be set when creating a campaign or when updating an existing campaign. However, once set, it can no longer be modified. When fetching an existing campaign which does not have a vendorId, the field is omitted. Inserting a new campaign with the same vendorId will still fail if you already have a campaign with that vendorId, regardless of its status. See Vendor Ids for more explanation.

title¶

A string of maximum 64 characters. This is purely a label for the seller, to potentially differentiate between multiple campaigns easier. This is not shown to buyers anywhere. This field will be omitted if the campaign does not have a title set.

isDefault¶

A boolean indicating whether this campaign is the default campaign for the seller or not. If so, any ads that will be placed without campaignId, will be added to this default campaign. Whenever we create a campaign under water for new sellers having no campaigns yet, these campaigns will automatically become the default campaign.

budgets¶

The budgets for this campaign. If either of these run out, ads from this campaign will no longer be visible on site.

budgets.daily¶

The daily budget for the campaign. Includes budgets.daily.limitMicros and budgets.daily.spentMicros.

budgets.total¶

The total budget for the campaign. Includes budgets.total.limitMicros and budgets.total.spentMicros.

budgets.daily.limitMicros¶

The maximum amount all the ads combined in this campaign may spend per day. When this amount is reached, the ads in this campaign will remain offline for the rest of the day.

budgets.total.limitMicros¶

The maximum amount all the ads combined in this campaign may spend. When this amount is reached, the ads in this campaign will remain offline until this limit has been increased.

budgets.daily.spentMicros¶

The amount all the ads combined in this campaign have spent so far, today. This will be reset every day around midnight.

budgets.total.spentMicros¶

The amount all the ads combined in this campaign have spent so far. This will never be reset.

Example¶

GET /campaign/123
Accept: application/sellside.campaign-v5+json, application/json

200 OK HTTP/1.1
Content-Type: application/sellside.campaign-v5+json; charset=UTF-8

{
    "id": 123,
    "dateCreated": "2022-12-25T10:04:23Z",
    "dateLastUpdated": "2022-12-28T22:40:15Z",
    "status": "ACTIVE",
    "vendorId": "123-abc-vjlkna-124",
    "title": "christmas stuff",
    "isDefault": true,
    "budgets": {
        "daily": {
            "limitMicros": "10000000",
            "spentMicros": "9520000",
        },
        "total": {
            "limitMicros": "UNLIMITED",
            "spentMicros": "124520000",
        }
    }
}