PUT /ad/{id}¶
PUT /ad/{id} v5 | PUT /ad/{id} v3 | PUT /ad/{id} v2
Warning
PUT /ad/{id} v2 is now officially deprecated and scheduled for removal on May, 1st 2023. Please move to use PUT /ad/{id} v5.
PUT /ad/{id} v3 is now officially deprecated and scheduled for removal on May, 1st 2023. Please move to use PUT /ad/{id} v5.
PUT /ad/{id} v5¶
Scope |
|
Accept |
|
Content-Type |
|
Note
Ads updated with PUT Ad V5 have a slightly different structure than GET /ad/{id} v3. It is correct that V4 is skipped.
The fields related to price are consolidated into one mandatory price object. |
The field campaignId is added. |
The daily and total budgets are now consolidated in one mandatory budgets object. |
CPC is no longer, it has changed into mandatory bidMicros. |
bidMicros, budgets.daily.limitMicros, budgets.daily.spentMicros, budgets.total.limitMicros and budgets.total.spentMicros are now all in micro currencies. |
several other fields are removed. See Fields for details. |
Example¶
PUT /ad/42
Accept: application/sellside.ad-v5+json, application/json
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",
},
"total": {
"limitMicros": "350000000",
}
},
"salutation": "COMPANY",
"sellerName": "My Shop",
"postcode": "1097DN",
"regionId": 1700195,
"phoneNumber": "0207894561",
"allowContactByEmail": true,
"vendorId": "OURSHOP-1423453-34",
"campaignId": 294012,
"links": {
"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",
},
{
"src": "http://www.ourshop.com/img/brother_fax_side.jpg",
}
],
"attributes": [
{
"key": "color",
"label": "Kleur",
"locale": "nl",
"type": "STRING",
"value": "Zwart",
},
{
"key": "size",
"label": "Maat",
"locale": "nl",
"type": "NUMBER",
"value": 6,
},
{
"key": "software",
"label": "Software",
"locale": "nl",
"type": "LIST",
"value": [
"Apple OSX",
"Microsoft Windows 7"
],
}
],
"shippingOptions": [
{
"type": "SHIP",
"costCents": 495,
"time": "2d-5d"
},
{
"type": "PICKUP",
"pickupLocation": "1097DN"
}
]
}
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"
}
},
"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",
"campaignId": 294012,
"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"
}
]
}
PUT /ad/{id} v3¶
Scope |
|
Accept |
|
Content-Type |
|
Version 3 works just like PUT /ad/{id} v2, except the response body contains an additional field statusReasons. This field is currently 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.
Example¶
PUT /ad/42
Accept: application/sellside.ad-v3+json, application/json
Content-Type: application/sellside.ad-v3+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,
"externalId": "OURSHOP-1423453-34",
"status": "ACTIVE",
"currency": "EUR",
"priceType": "FIXED_PRICE",
"priceUnit": "per_sqm",
"price": 9999,
"cpc": 10,
"totalBudget": 5000,
"dailyBudget": 2000,
"salutation": "COMPANY",
"sellerName": "My Shop",
"postcode": "1097DN",
"phoneNumber": "0207894561",
"allowContactByEmail": true,
"allowPaypal": true,
"vendorId": "OURSHOP-1423453-34",
"links": {
"url": "http://www.ournewshop.com/index.php?param1=value1&param2=value2&param3=value3",
"displayUrl": "www.ournewshop.com/Faxes"
},
"images": [
{
"src": "http://images.ourshop.com/source1.jpg"
},
{
"src": "http://images.ourshop.com/source2.jpg"
},
{
"src": "http://images.ourshop.com/source3.jpg"
}
],
"attributes": [
{
"key": "color",
"label": "Kleur",
"locale": "nl",
"type": "STRING",
"value": "Zwart"
},
{
"key": "color",
"label": "Color",
"locale": "en",
"type": "STRING",
"value": "Black"
},
{
"key": "size",
"label": "Maat",
"locale": "nl",
"type": "NUMBER",
"value": 6
},
{
"key": "software",
"label": "Software",
"type": "LIST",
"locale": "nl",
"value": [
"Apple OSX",
"Microsoft Windows 7"
]
}
],
"shippingOptions": [
{
"type": "SHIP",
"cost": 0,
"time": "2d-5d"
},
{
"type": "PICKUP",
"pickupLocation": "1097DN"
}
]
}
200 OK
Content-Type: application/sellside.ad-v3+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,
"externalId": "OURSHOP-1423453-34",
"status": "PAUSED",
"currency": "EUR",
"priceType": "FIXED_PRICE",
"priceUnit": "per_sqm",
"price": 9999,
"cpc": 10,
"totalBudget": 5000,
"dailyBudget": 2000,
"salutation": "COMPANY",
"sellerName": "My Shop",
"postcode": "1097DN",
"phoneNumber": "0207894561",
"allowContactByEmail": true,
"allowPaypal": true,
"vendorId": "OURSHOP-1423453-34",
"links": {
"url": "http://www.ournewshop.com/index.php?param1=value1&param2=value2&param3=value3",
"displayUrl": "www.ournewshop.com/Faxes"
},
"images": [
{
"src": "http://images.ourshop.com/source1.jpg"
},
{
"src": "http://images.ourshop.com/source2.jpg"
},
{
"src": "http://images.ourshop.com/source3.jpg"
}
],
"attributes": [
{
"key": "color",
"label": "Kleur",
"locale": "nl",
"type": "STRING",
"value": "Zwart"
},
{
"key": "color",
"label": "Color",
"locale": "en",
"type": "STRING",
"value": "Black"
},
{
"key": "size",
"label": "Maat",
"locale": "nl",
"type": "NUMBER",
"value": 6
},
{
"key": "software",
"label": "Software",
"type": "LIST",
"locale": "nl",
"value": [
"Apple OSX",
"Microsoft Windows 7"
]
}
],
"shippingOptions": [
{
"type": "SHIP",
"cost": 0,
"time": "2d-5d"
},
{
"type": "PICKUP",
"pickupLocation": "1097DN"
}
],
"statusReasons": [
"DOMAIN_PENDING"
]
}
PUT /ad/{id} v2¶
Scope |
|
Accept |
|
Content-Type |
|
This URL updates the ad with the given id.
If the ad was successfully updated then a 200 OK is returned. The
optional query parameter _body with value true or false can be
used to influence whether the response body contains the ad in the body (or
not) in case of success. By default, this value is true. If the ad does not
exist or does not belong to the user the server returns 404 Not Found. If
the id is invalid, i.e. not a positive integer the server returns 400
Bad Request.
Note
Updating deleted ads is not allowed and will result in a 400 Bad Request.
All writeable fields listed in Fields can be changed. Attempting to change a non-writeable field results in a 400 Bad Request
All validation rules for creating an ad apply exactly the same.
Additionally, the following rules apply:
The totalBudget cannot be lower than the minimum budget as defined in the category and also cannot be lower than the sum of cpc and the current value of spentBudget. Similarly, the dailyBudget cannot be lower than than the minimum daily budget as defined in the category and also cannot be lower than the sum of cpc and the current value of dailySpent.
Note
The value of dailySpent is not exposed via the API.
Note
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
Parameters¶
Name |
Type |
Default |
Description |
|---|---|---|---|
_body |
boolean |
true |
Include the modified ad in the response body on success. Disabling this will speed up the call. Setting this to false will override any _include or _exclude. |
_include |
string |
“” |
Comma-separated-list of fields to include. |
_exclude |
string |
“” |
Comma-separated-list of fields to omit. |
_validate |
boolean |
false |
Validate the request without executing it. |
Errors¶
Additional error codes for PUT /ad/{id}.
Field |
Code |
Error message |
Description |
|---|---|---|---|
status |
2001 |
invalid argument |
must be either ACTIVE, PAUSED or DELETED |
totalBudget |
2002 |
out of range |
totalBudget is not within max(category.minBudget, ad.spentBudget) and category.maxBudget |
categoryId |
2012 |
category change not allowed |
Changing the category of an ad is not allowed |
status |
2017 |
ad status change not allowed |
Changing the status of an ad is not allowed |
totalBudget |
2019 |
insufficient budget |
Budget for ad is insufficient |
dailyBudget |
2020 |
insufficient daily budget |
Daily budget for ad is insufficient |
categoryId |
2023 |
category deleted |
The category has been deleted and will not allow creation/updating of ads |
Note
It is _not_ allowed to edit deleted ads (DELETED or DELETED_BY_CS status).
Error codes for POST /ad.
Field |
Code |
Error message |
Description |
|---|---|---|---|
allowContactByEmail |
2001 |
invalid argument |
must be true or false |
allowPaypal |
2001 |
invalid argument |
must be true or false |
attribute.name |
2000 |
missing argument |
one of the attributes is wrong: missing the field ‘name’ |
attribute.name |
2004 |
value too short |
one of the attributes is wrong: need at least 1 non-space character |
attribute.name |
2005 |
value too long |
one of the attributes is wrong: max. length is 32 characters |
attribute.type |
2000 |
missing argument |
one of the attributes is wrong: missing the field ‘type’ |
attribute.type |
1006 |
type mismatch |
one of the attributes is wrong: unknown type |
attribute.value |
2000 |
missing argument |
one of the attributes is wrong: missing the field ‘value’ |
attribute.value |
2004 |
value too short |
one of the attributes is wrong: need at least 1 non-space character |
attribute.value |
2005 |
value too long |
one of the attributes is wrong: max. length is 512 characters |
attribute.value |
2001 |
invalid argument |
one of the attributes has a wrong value type for provided ‘type’ |
categoryId |
1006 |
type mismatch |
not an integer number |
categoryId |
2000 |
missing argument |
mandatory field |
categoryId |
2001 |
invalid argument |
not a valid category id |
categoryId |
2022 |
category not active |
category is not active and will not allow creation of ads |
categoryId |
2023 |
category deleted |
category is deleted and will not allow creation/updating of ads |
cpc |
1006 |
type mismatch |
not an integer number |
cpc |
2000 |
missing argument |
mandatory field |
cpc |
2002 |
out of range |
value not between category.minCpc and category.maxCpc |
currency |
2000 |
missing argument |
mandatory field |
currency |
2001 |
invalid argument |
not “EUR” or “CAD” |
dailyBudget |
1006 |
type mismatch |
not an integer number |
dailyBudget |
2002 |
out of range |
value lower than category.minDailyBudget or higher than totalBudget |
description |
2000 |
missing argument |
mandatory field |
description |
2002 |
out of range |
too short or too long; see Categories about the constraints. |
externalId |
2005 |
value too long |
too short or too long; see Categories about the constraints. |
id |
1006 |
type mismatch |
not an integer number |
id |
2001 |
invalid argument |
id must be omitted or set to zero |
images.size |
2002 |
out of range |
too many image URLs |
images.url |
2006 |
invalid url |
invalid image URL |
links.displayUrl |
2005 |
value too long |
max. length is 255 |
links.url |
2005 |
value too long |
max. length is 2048 |
links.url |
2006 |
invalid url |
is not a valid url |
phoneNumber |
2005 |
value too long |
max. length is 32 |
phoneNumber |
2010 |
invalid phone number |
not a valid phone number |
postcode |
2005 |
value too long |
max. length is 6 |
price |
1006 |
type mismatch |
not an integer number |
price |
2000 |
missing argument |
not specifying a price for a priceType which requires a price |
price |
2001 |
invalid argument |
specifying a price for a priceType without a price |
price |
2002 |
out of range |
price is not in the interval of |
priceType |
2001 |
invalid argument |
not a valid price type |
salutation |
2001 |
invalid argument |
not a valid salutation |
sellerName |
2000 |
missing argument |
must not be empty |
sellerName |
2005 |
value too long |
max. length is 60 |
status |
2000 |
missing argument |
mandatory field |
status |
2001 |
invalid argument |
must be either ACTIVE or PAUSED |
title |
2000 |
missing argument |
mandatory field |
title |
2002 |
out of range |
max. length is 60 |
totalBudget |
1006 |
type mismatch |
not an integer number |
totalBudget |
2002 |
out of range |
value too low/high |
vendorId |
2005 |
value too long |
max. length is 64 characters |
Example¶
PUT /ad/42
Accept: application/sellside.ad-v2+json, application/json
Content-Type: application/sellside.ad-v2+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,
"externalId": "OURSHOP-1423453-34",
"status": "ACTIVE",
"currency": "EUR",
"priceType": "FIXED_PRICE",
"priceUnit": "per_sqm",
"price": 9999,
"cpc": 10,
"totalBudget": 5000,
"dailyBudget": 2000,
"salutation": "COMPANY",
"sellerName": "My Shop",
"postcode": "1097DN",
"phoneNumber": "0207894561",
"allowContactByEmail": true,
"allowPaypal": true,
"vendorId": "OURSHOP-1423453-34",
"microTip": "high quality",
"links": {
"url": "http://www.ourshop.com/index.php?param1=value1&param2=value2&param3=value3",
"displayUrl": "www.ourshop.com/Faxes"
},
"images": [
{
"src": "http://images.ourshop.com/source1.jpg"
},
{
"src": "http://images.ourshop.com/source2.jpg"
},
{
"src": "http://images.ourshop.com/source3.jpg"
}
],
"attributes": [
{
"key": "color",
"label": "Kleur",
"locale": "nl",
"type": "STRING",
"value": "Zwart"
},
{
"key": "color",
"label": "Color",
"locale": "en",
"type": "STRING",
"value": "Black"
},
{
"key": "size",
"label": "Maat",
"locale": "nl",
"type": "NUMBER",
"value": 6
},
{
"key": "software",
"label": "Software",
"type": "LIST",
"locale": "nl",
"value": [
"Apple OSX",
"Microsoft Windows 7"
]
}
],
"shippingOptions": [
{
"type": "SHIP",
"cost": 0,
"time": "2d-5d"
},
{
"type": "PICKUP",
"pickupLocation": "1097DN"
}
],
"paypalEmail": "test@example.com"
}