Advertisements¶
Advertisements or ads are the main resource on the Sellside API. You can create, update and delete them, change the status and get a list of your ads. Through the API you only have access to your own ads. Ads from other advertisers are not accessible to you.
Fields¶
Each ad has a unique identifier by which the ad can retrieved and a set of required and optional fields which are listed below:
Field |
Type |
Deprecated in |
Constraints |
Mandatory |
Writable |
|---|---|---|---|---|---|
long |
– |
positive |
– |
no |
|
string |
– |
see below |
yes |
yes |
|
string |
– |
see below |
yes |
yes |
|
int |
– |
positive |
yes |
no |
|
string |
– |
enum |
yes |
yes |
|
object |
– |
yes |
yes |
yes |
|
int |
– |
>= 0 |
no |
yes |
|
string |
– |
enum |
yes |
yes |
|
string |
– |
string, see below |
no |
no |
|
int |
– |
>= 0, >amountCents |
no |
yes (if user is allowed) |
|
string |
– |
enum |
yes |
yes |
|
string |
– |
max. 60 chars |
yes |
yes |
|
string |
– |
max. 6 chars |
no |
yes |
|
long |
– |
positive |
no |
yes (only during create) |
|
string |
– |
max. 32 chars |
no |
yes |
|
bool |
– |
– |
no |
yes |
|
date |
– |
readonly |
no |
no |
|
date |
– |
readonly |
no |
no |
|
date |
– |
readonly |
no |
no |
|
object |
– |
see below |
no |
yes |
|
string |
– |
max. 2048 chars |
no |
no |
|
string |
– |
max. 2048 chars |
no |
no |
|
string |
– |
max. 2048 chars |
no |
yes |
|
string |
– |
max. 256 chars |
no |
yes |
|
array |
– |
see below |
no |
yes |
|
array |
– |
– |
no |
yes |
|
array |
– |
see below |
yes |
yes |
|
string |
– |
max. 64 chars |
no |
yes (if not set already) |
|
string |
– |
max. 18 chars |
no |
yes (if user is allowed) |
|
long |
– |
positive |
see below |
yes |
|
string |
– |
see below |
yes |
yes |
|
object |
– |
see below |
yes |
yes |
|
object |
– |
see below |
yes |
yes |
|
object |
– |
see below |
yes |
yes |
|
string |
– |
see below |
yes |
yes |
|
string |
– |
see below |
no |
no |
|
string |
– |
see below |
yes |
yes |
|
string |
– |
see below |
no |
no |
|
string |
– |
max. 64 chars |
no |
yes |
|
string |
V5 |
cat.Currency |
yes |
no |
|
string |
V5 |
enum |
yes |
yes |
|
string |
V5 |
see below |
no |
yes |
|
long |
V5 |
see below |
see below |
yes |
|
long |
V5 |
positive |
yes |
yes |
|
string |
V5 |
– |
– |
no |
|
long |
V5 |
positive |
no |
yes |
|
long |
V5 |
positive |
no |
yes |
|
long |
V5 |
positive |
– |
no |
|
long |
V5 |
positive |
– |
no |
|
int |
V5 |
– |
no |
no |
|
long |
V5 |
– |
no |
no |
|
bool |
V3 |
no |
yes |
yes |
Note
We introduce a new monetary unit of micros across our product, where one cent equals 10000 micros. One micro is 1-millionth of the local tenant currency. This will allow for a higher level of granularity when specifying the cost (per click).
We are substituting the current CPC values across the API with a bid value, and the actual (incurred) billed cost value - this to allow for better differentiation between the two. This split between bid and billed values is currently utilised for an experimental feature which adjusts the bid value for the quality of the traffic.
This new micros unit, as well as the distinction between bid and billed cost, are to become a core part of the product. We will gradually deprecate any fields with cents and local currency units across the API.
id¶
Unique reference to the ad, needs to be omitted in a POST action.
title¶
Any string, with minimum and maximum length determined by the category. See Categories. URLs are not allowed as part of the title.
description¶
The description field of the ad. Any string, with minimum and maximum length determined by the category. See Categories. URLs are not allowed as part of the title. All HTML elements except for the ones below will be removed:
<i> <em> <b> <strong> <ul> <li> <u> <br/>
categoryId¶
The category in which the ad is placed.
Each ad belongs to one and only one category; this can be updated.
An integer value from the category list. Must be an id of a category with a non-zero parent id.
externalId¶
Warning
externalId is deprecated, please transition to vendorId
Any non-empty string with a maximum length of 64 characters. When fetching an existing ad which does not have an externalId, the field is empty or omitted. There is no unique constraint when it comes to externalId, so multiple ads are allowed to have the same externalId.
status¶
Is a valid value from the list of Ad Status. The user can set only one of the user controlled states ACTIVE, PAUSED or DELETED.
currency¶
The ISO 4217 currency code. Currently only EUR, and CAD supported. All values are stored in cents (1/100 parts), i.e. EUR 10.50 are represented as 1050, CAD 12.34 should be represented as 1234. Deprecated in V5, all monetary values are in the currency of the country you are placing for.
priceType¶
Must be a valid price type identifier from the list of Price Types. Deprecated in V5, use price.priceType instead.
priceUnit¶
Must be a valid price unit identifier from the list of available price units of the category. Deprecated in V5, use price.priceUnit instead.
price¶
The meaning of the value depends on priceType. If it is
FIXED_PRICE or BIDDING_FROM then price has to be greater than 0.
The maximum allowed price is 10000000000 Euro cents (100.000.000 Euros).
Deprecated in V5, use price instead.
price¶
Price is an object containing all the information about the cost of the item for sale. This includes price.amountCents, price.priceType price.priceUnit and price.originalAmountCents.
price.amountCents¶
The cost of the item (without shipping costs) in cents.
The meaning of the value depends on price.priceType. If it is
FIXED_PRICE or BIDDING_FROM then price.amountCents has to be greater than 0.
The maximum allowed price.amountCents is 10000000000 Euro cents (100.000.000 Euros).
price.priceType¶
Must be a valid price type identifier from the list of Price Types.
price.priceUnit¶
Must be a valid price unit identifier from the list of available price units of the category.
price.originalAmountCents¶
The cost of the item (without shipping costs) in cents, before discount was applied. Not available to all users. Needs to be larger than price.amountCents.
statusReasons¶
used to indicate the reason why a certain ad might be set to a certain status by our system. This could be due to, for example, an action (like new website domain approval) pending from the user, which is a mechanism used to prevent account takeovers from setting the website URL to a malicious one. Deprecated in V4, status’s enums have been expanded.
campaignId¶
identifier of the campaign this ad belongs to. See Campaigns for more info. This is not mandatory, and we will add the ad to the default campaign if not provided. For the time being, we will also create the (default) campaign underwater if the seller has no campaign created yet, to ensure there is one for the seller.
bidMicros¶
The cost per click (bid) in micro-euros/micro-dollars as defined by the seller (10000 micro-euros == 1 cent). The minimum and maximum values depend on the category. The type is string, allowing the seller to specify “AUTOMATIC”, to let our system take care of the bid and try to optimise costs vs clicks.
cpc¶
The cost per click in cents as defined by the seller in cents. The minimum and maximum values depend on the category. Deprecated, replaced by bidMicros in V5.
budgets¶
a struct encapsulating both budgets.daily and budgets.total.
budgets.daily¶
a struct encapsulating both budgets.daily.limitMicros and budgets.daily.spentMicros
budgets.total¶
a struct encapsulating both budgets.total.limitMicros and budgets.total.spentMicros
budgets.daily.limitMicros¶
the maximum amount this ad can spend today in micros, after which it will be taken offline for the remainder of the day.
budgets.total.limitMicros¶
the maximum amount this ad can spend in micros, after which it will be taken offline until the seller increases the limit.
budgets.daily.spentMicros¶
the amount spent in micros on this ad sofar, for today. Will be reset back to 0 at midnight.
budgets.total.spentMicros¶
the amount spent in micros on this ad in its lifetime. Will be ever increasing and cannot be reset.
totalBudget¶
The total budget for the ad. The minimum and maximum values depend on the category. When an ad is updated this value cannot be lower than the spentBudget. If the total budget is not returned with the ad, it means there is an unlimited total budget. Deprecated, replaced by budgets.total in V5.
dailyBudget¶
The daily budget for the ad. When this value is reached the ad will be paused
for the rest of the day. The minimum value depends on the category. Maximum value
cannot be higher than the totalBudget
To disable the dailyBudget for an ad set it to null.
Deprecated, replaced by budgets.daily in V5.
dailySpent¶
The budget spent for the ad since midnight.
Only provided when the dailyBudget is not null and > 0.
Deprecated, replaced by budgets.daily.spentMicros in V5.
spentBudget¶
The total amount of the budget that has been used so far. Deprecated, replaced by budgets.total.spentMicros in V5.
salutation¶
The salutation as used in emails. Must be a valid salutation identifier from MALE, FEMALE, COMPANY or FAMILY
sellerName¶
Display name of the seller (max. 60 characters).
postcode¶
Must be an non empty string.
regionId¶
The region in which the ad is placed. A long value from the region tree. Can be the ID from any node.
Each ad belongs to one and only one region and region of an ad cannot be updated. This field can only set once during creation of an ad.
This field is mandatory if the region field of category configuration is MANDATORY
and optional if the region field is OPTIONAL.
This field must be omitted if the region field of category configuration is DISABLED.
Please refer to Categories and Regions
pageNumber¶
Page number on which this ad is shown. Page number is highly volatile and might change very quickly depending on the performance of the ad.
The fields pageNumber and suggestedCpcForPageOne are currently expensive to compute. If you do not need their values consider excluding them to speed up the response. To exclude the fields add the following parameter to the request URL.
?_exclude=pageNumber,suggestedCpcForPageOne
Deprecated, removed in V5.
suggestedCpcForPageOne¶
Suggested CPC value in (euro/dollar) cents for this ad to be shown on page one.
This value is very volatile and might change very quickly depending on the
performance of the ad. If the returned value is -1 then there is no CPC within
the allowed range of the category to put this ad on page 1.
The fields pageNumber and suggestedCpcForPageOne are currently expensive to compute. If you do not need their values consider excluding them to speed up the response. To exclude the fields add the following parameter to the request URL.
?_exclude=pageNumber,suggestedCpcForPageOne
Deprecated, removed in V5.
phoneNumber¶
The phone number of the advertiser as international phone number format, e.g. +31207894561 or as a local phone number, e.g. 06789456612.
allowContactByEmail¶
Flag for allowing emails to be sent to the advertiser.
allowPaypal¶
Flag for allowing PayPal as a payment option. Deprecated, removed in V3.
dateCreated¶
The ISO 8601 UTC date and time the ad was created.
dateLastUpdated¶
The ISO 8601 UTC date and time the ad was last updated.
dateDeleted¶
The ISO 8601 UTC date and time the ad was deleted. Omitted if the ad is still active or paused.
links¶
An object encapsulating links.self, links.category, links.url and links.displayUrl
links.self¶
A link referencing the current ad. This will be provided by the Sellside API.
links.category¶
A link referencing the category the ad is placed in. This will be provided by the Sellside API.
links.url¶
An external URL that is shown on the ad page. This must be a valid http(s) url.
links.displayUrl¶
The text/url that will be displayed instead of the url in links.url.
vendorId¶
Any non-empty string with a maximum length of 64 characters. Please use simple latin-1 characters only.
Should be unique per customer. Can either be set when creating an ad or when updating an
existing ad. However, once set, it can no longer be modified. When fetching an
existing ad which does not have a vendorId, the field is omitted.
When an ad gets set to status DELETED, this does not remove the vendorId.
This means that inserting a new ad with the same vendorId will still fail if you
already have an ad with that vendorId, regardless of its status. See Vendor Ids for more explanation.
microTip¶
A short freeform text with a maximum length of 18 characters, excluding any characters in .,/@#<>.
It is a feature as part of a package that sellers can purchase (currently available only for Marktplaats tenant).
It provides extra attention on the ad in the search results.
At the time of writing, this will only have an effect on ads created via the Console.
However, it can be adjusted through the API.
Images¶
Each ad can contain up to X images (range is defined per category in the taxonomy) which can be provided by the caller as a set of URLs. The system will download the images and if they meet the requirements then they will be stored on our servers in several sizes so that they can then be used by the user.
An image is valid if it is in JPG, PNG, GIF or BMP format and is smaller than 8MB in size. Images larger than 1024x1024 px are being scaled down.
The images will be shown in the order they are provided. The first image is shown in search results and it is the main image on the item page.
Image Objects¶
When an ad is created or updated the caller provides the images as a list of image objects which contain only the source url.
"images": [
{
"src": "http://www.ourshop.com/img/brother_fax_big.jpg",
},
...
]
The images are then downloaded by the system and we add some additional fields which describe the status of the download.
"images": [
{
"src": "http://www.ourshop.com/img/brother_fax_big.jpg",
"status": "OK",
"dateLastUpdated": "2012-09-10T13:11:05Z",
"links": {
"50x70": "//i.marktplaats.nl/image23434_abc.jpg",
"120x180": "//i.marktplaats.nl/image23434_def.jpg",
}
}
...
]
The server adds a status field indicating the status of the download. The
status is either OK (image was successfully downloaded), PENDING
(image is scheduled to be downloaded) or ERROR if the image was not found
or invalid.
If the status is OK then a links map is added which contains
protocol agnostic links to copies on our servers of the uploaded image
in various sizes. The dimensions are specified as max width x max height.
The server also adds the dateLastUpdated field which specifies the time
the image was last updated.
Note
The caller can provide all the fields added by the server since they will be ignored.
attributes¶
An optional list of User-Defined Attributes.
shippingOptions¶
A list of shipping options available for an ad. Ads can contain maximum one shipping option per shipping option type. Whether shipping options are disabled/optional/mandatory for an ad is configured per category, see Category Configuration.
Shipping option has the following fields:
Field |
Mandatory |
Deprecated in |
Description |
|---|---|---|---|
type |
Mandatory |
SHIP or PICKUP. SHIP means the item can be delivered to the buyer in the provided time and for the provided cost. PICKUP means the item can be picked up at the provided location. |
|
cost |
Optional |
V5 |
Deprecated, use costCents. Cost of shipping in cents. Only valid when type is SHIP. Must be greater than or equal to 0. Field can be omitted if costs are unknown. |
costCents |
Optional |
Cost of shipping in cents. Only valid when type is SHIP. Must be greater than or equal to 0. Field can be omitted if costs are unknown. |
|
time |
Optional |
Time it takes to deliver the ad. Only valid when type is SHIP. Supported values are “2d-5d”, “6d-10d” and everything in the form “<number>d” where <number> is > 0. Field can be omitted if time is unknown. |
|
pickupLocation |
Mandatory when type is PICKUP |
Pick up location of the item, in postcode structure. |
shippingOptions example¶
"shippingOptions": [
{"type": "SHIP", "costCents": 0, "time":"2d-5d"},
{"type": "PICKUP", "pickupLocation":"1097DN"}
]
Ad Example¶
GET /ad/42
Accept: application/sellside.ad-v5+json, application/json
200 OK
Content-Type: application/sellside.ad-v5+json; charset=utf-8
{
"id": 42,
"title": "Brother Fax voor 99,99",
"description": "<b>NU extra voordelig op ourshop.com.</b> Fax nu voor slechts <b>99,99!</b>",
"categoryId": 826,
"status": "ACTIVE",
"price": {
"priceType": "FIXED_PRICE",
"priceUnit": "per_sqm",
"amountCents": 5600,
"originalAmountCents": 6500
},
"bidMicros": "10000",
"budgets": {
"daily": {
"limitMicros": "UNLIMITED",
"spentMicros": "1255000"
},
"total": {
"limitMicros": "350000000",
"spentMicros": "24370000"
}
},
"campaignId": 54212,
"salutation": "COMPANY",
"sellerName": "My Shop",
"postcode": "1097DN",
"regionId": 1700195,
"phoneNumber": "0207894561",
"allowContactByEmail": true,
"dateCreated": "2012-08-31T16:12:53Z",
"dateLastUpdated": "2012-09-05T04:03:42Z",
"vendorId": "OURSHOP-1423453-34",
"links": {
"self": "/ad/42",
"category": "/category/826",
"displayUrl": "www.ourshop.com/Faxes",
"url": "http://www.ourshop.com/index.php?param1=value1&param2=value2&param3=value3"
},
"images": [
{
"src": "http://www.ourshop.com/img/brother_fax_big.jpg",
"status": "OK",
"dateLastUpdated": "2012-09-10T13:11:05Z",
"links": {
"50x70": "//i.marktplaats.nl/image23434_abc.jpg",
"120x180": "//i.marktplaats.nl/image23434_def.jpg"
}
},
{
"src": "http://www.ourshop.com/img/brother_fax_side.jpg",
"status": "OK",
"dateLastUpdated": "2012-09-10T13:11:05Z",
"links": {
"50x70": "//i.marktplaats.nl/image397493_abc.jpg",
"120x180": "//i.marktplaats.nl/image397493_def.jpg"
}
}
],
"attributes": [
{
"key": "color",
"label": "Kleur",
"locale": "nl",
"type": "STRING",
"value": "Zwart",
"recognized": true
},
{
"key": "size",
"label": "Maat",
"locale": "nl",
"type": "NUMBER",
"value": 6,
"recognized": true
},
{
"key": "software",
"label": "Software",
"locale": "nl",
"type": "LIST",
"value": [
"Apple OSX",
"Microsoft Windows 7"
],
"recognized": false
}
],
"shippingOptions": [
{
"type": "SHIP",
"costCents": 495,
"time": "2d-5d"
},
{
"type": "PICKUP",
"pickupLocation": "1097DN"
}
]
}