Migration Guide¶

Purpose: This guide is designed to help API partners migrate from older deprecated API versions (v2, v3, v4) to the latest version (v5) of the Sellside API.

Key changes and benefits of migrating¶

○ Autobidding allows the use of an automated (smart) bidding strategy. [See more here (in Dutch)](https://help.marktplaats.nl/s/article/marktplaats-pro-automatische-cost-per-click-instellingen)
○ Introducing micros as the monetary unit enables more precise cost management, allowing finer granularity in ad spending and budget allocation. 1 cent is equal to 10000 micros.
○ Improved pagination with the more efficient industry-standard pageToken, as a replacement for the old offset/limit pagination mechanism.
○ Optional campaign (and campaign budget) management allows for better control over spending, by setting a campaign-level budget as well as pausing an entire campaign, effectively taking all the ads in the campaign offline.
○ Budgets and price fields are streamlined into a clear format, improving accuracy and consistency across the API. The Step By Step guide explains how to convert the values to the new format.
○ Removal of pageNumber & suggestedCpcForPageOne from ad and category endpoints.

Context: In the desktop era, most traffic came from leaf category browse actions, leading to the introduction of the “suggested CPC for page one.” However, as traffic sources have diversified to include search actions and personalized recommendations, the relevance of these fields has decreased.

The removal reflects the shift towards a more dynamic and diverse traffic landscape where different ranking methods are more effective. This simplifies ad management by removing outdated metrics.

Step by step guide¶

This section provides a detailed view of the changes for each affected API endpoint, mapping fields from the old and deprecated versions to the new v5. Follow this guide to understand the modifications and learn how to update your implementation for a smooth migration.

Each API endpoint is presented in a expandable/collapsible section, with the deprecated and new versions side by side for easy comparison.

GET /ad/{id}

Response payload: deprecated version

{
  // ...
  "statusReasons": ["DOMAIN_PENDING"],
  "priceType": "FIXED_PRICE",
  "currency": "EUR",
  "price": 5600,
  "originalPrice": 6500,
  "cpc": 15,
  "totalBudget": 1000,
  "dailyBudget": 500,
  "spentBudget": 120,
  "dailySpent": 50,
  "pageNumber": 2,
  "suggestedCpcForPageOne": 15,
  "allowPayPal": true,
  "shippingOptions": [
    {
      "cost": 500,
      "time": "2d-5d"
    }
  ]
}

Response payload: new version

{
  // ...
  "price": {
    "amountCents": 5600,
    "originalAmountCents": 6500,
    "priceType": "FIXED_PRICE"
  },
  "campaignId": 54212,
  "bidMicros": "10000",
  "budgets": {
    "daily": {
      "limitMicros": "UNLIMITED",
      "spentMicros": "500000"
    },
    "total": {
      "limitMicros": "10000000",
      "spentMicros": "1200000"
    }
  },
  "shippingOptions": [
    {
      "costCents": 500,
      "time": "2d-5d"
    }
  ]
}

Mapping details

Deprecated media type(s): application/sellside.ad-v2+json application/sellside.ad-v3+json
New media type: application/sellside.ad-v5+json
Price: price and originalPrice map to price.amountCents and price.originalAmountCents respectively. The value was already in cents so there is no need for conversion.
CPC: cpc is replaced by bidMicros, and is represented as a string type, instead of integer. This requires a conversion of the values from a micros unit, when interpreting them as cents.
Budget Fields: dailyBudget and totalBudget map to budgets.daily.limitMicros and budgets.total.limitMicros respectively. dailySpent and spentBudget map to budgets.daily.spentMicros and budgets.total.spentMicros. Values are represented in string type, instead of integer, and at micro precision, instead of cents. The limits can also be "UNLIMITED".
Shipping Cost: cost is renamed to costCents in V5. The value was already in cents so there is no need for conversion.
Removed field(s): statusReasons, pageNumber, suggestedCpcForPageOne, currency, allowPayPal. The field vendorId should be used instead of externalId, which is deprecated and planned for removal.
New field(s): campaignId: this is an identifier for the campaign which this ad is part of. Campaign management is optional. By default, every seller has one campaign associated with them, with every ad attached to that campaign. See Campaigns for more.
If necessary, position (page number and suggested cost per click) funnel information can be obtained from the replacement GET /ad/{id}/position endpoint (see the FAQ).

GET /ad/byVendor/{vendorId}

Response payload: deprecated version

{
  // ...
  "statusReasons": ["DOMAIN_PENDING"],
  "priceType": "FIXED_PRICE",
  "currency": "EUR",
  "price": 5600,
  "originalPrice": 6500,
  "cpc": 15,
  "totalBudget": 1000,
  "dailyBudget": 500,
  "spentBudget": 120,
  "dailySpent": 50,
  "pageNumber": 2,
  "suggestedCpcForPageOne": 15,
  "allowPayPal": true,
  "shippingOptions": [
    {
      "cost": 500,
      "time": "2d-5d"
    }
  ]
}

New version

{
  // ...
  "price": {
    "amountCents": 5600,
    "originalAmountCents": 6500,
    "priceType": "FIXED_PRICE"
  },
  "campaignId": 54212,
  "bidMicros": "10000",
  "budgets": {
    "daily": {
      "limitMicros": "UNLIMITED",
      "spentMicros": "500000"
    },
    "total": {
      "limitMicros": "10000000",
      "spentMicros": "1200000"
    }
  },
  "shippingOptions": [
    {
      "costCents": 500,
      "time": "2d-5d"
    }
  ]
}

Mapping details

Deprecated media type(s): application/sellside.ad-v2+json application/sellside.ad-v3+json
New media type: application/sellside.ad-v5+json
Price: price and originalPrice map to price.amountCents and price.originalAmountCents respectively. The value was already in cents so there is no need for conversion.
CPC: cpc is replaced by bidMicros, and is represented as a string type, instead of integer. This requires a conversion of the values from a micros unit, when interpreting them as cents.
Budget Fields: dailyBudget and totalBudget map to budgets.daily.limitMicros and budgets.total.limitMicros respectively. dailySpent and spentBudget map to budgets.daily.spentMicros and budgets.total.spentMicros. Values are represented in string type, instead of integer, and at micro precision, instead of cents. The limits can also be "UNLIMITED".
Shipping Cost: cost is renamed to costCents in V5. The value was already in cents so there is no need for conversion.
Removed field(s): statusReasons, pageNumber, suggestedCpcForPageOne, currency, allowPayPal. The field vendorId should be used instead of externalId, which is deprecated and planned for removal.
New field(s): campaignId: this is an identifier for the campaign which this ad is part of. Campaign management is optional. By default, every seller has one campaign associated with them, with every ad attached to that campaign. See Campaigns for more.
If necessary, position (page number and suggested cost per click) funnel information can be obtained from the replacement GET /ad/{id}/position endpoint (see the FAQ).

POST /ad

Request payload: deprecated version

{
  // ...
  "priceType": "FIXED_PRICE",
  "currency": "EUR",
  "price": 5600,
  "originalPrice": 6500,
  "cpc": 15,
  "totalBudget": 1000,
  "externalId": "OUR-SHOP-123",
  "allowPayPal": true,
  "shippingOptions": [
    {
      "cost": 500,
      "time": "2d-5d"
    }
  ]
}

Request payload: new version

{
  // ...
  "price": {
    "amountCents": 5600,
    "originalAmountCents": 6500,
    "priceType": "FIXED_PRICE"
  },
  "vendorId": "OUR-SHOP-123",
  "bidMicros": "10000",
  "budgets": {
    "daily": {
      "limitMicros": "UNLIMITED",
    },
    "total": {
      "limitMicros": "10000000",
    }
  },
  "shippingOptions": [
    {
      "costCents": 500,
      "time": "2d-5d"
    }
  ]
}

Mapping details

Deprecated media type(s): application/sellside.ad-v2+json application/sellside.ad-v3+json
New media type: application/sellside.ad-v5+json
Price: price and originalPrice map to price.amountCents and price.originalAmountCents respectively. The value was already in cents so there is no need for conversion.
CPC: cpc is replaced by bidMicros. This requires a conversion of the values to a micros unit, and supplying it as string type, instead of integer.
Budget Fields: daiyBudget and totalBudget map to budgets.daily.limitMicros and budgets.total.limitMicros respectively. dailySpent and spentBudget map to budgets.daily.spentMicros and budgets.total.spentMicros. Beware that they are now mandatory to supply. Values should be supplied in string type, instead of integer, and at micro precision, instead of cents. The budget limits can also be "UNLIMITED".
Shipping Cost: cost is renamed to costCents. The value was already in cents so there is no need for conversion.
Removed field(s): currency, allowPayPal. externalId is marked as deprecated and planned for removal, please use vendorId instead.

PUT /ad/{id}

Request payload: deprecated version

{
  // ...
  "priceType": "FIXED_PRICE",
  "currency": "EUR",
  "price": 5600,
  "originalPrice": 6500,
  "cpc": 15,
  "totalBudget": 1000,
  "externalId": "OUR-SHOP-123",
  "allowPayPal": true,
  "shippingOptions": [
    {
      "cost": 500,
      "time": "2d-5d"
    }
  ]
}

Request payload: new version

{
  // ...
  "price": {
    "amountCents": 5600,
    "originalAmountCents": 6500,
    "priceType": "FIXED_PRICE"
  },
  "vendorId": "OUR-SHOP-123",
  "bidMicros": "10000",
  "budgets": {
    "daily": {
      "limitMicros": "UNLIMITED",
    },
    "total": {
      "limitMicros": "10000000",
    }
  },
  "shippingOptions": [
    {
      "costCents": 500,
      "time": "2d-5d"
    }
  ]
}

Mapping details

Deprecated media type(s): application/sellside.ad-v2+json application/sellside.ad-v3+json
New media type: application/sellside.ad-v5+json
Price: price and originalPrice map to price.amountCents and price.originalAmountCents respectively. The value was already in cents so there is no need for conversion.
CPC: cpc is replaced by bidMicros. This requires a conversion of the values to a micros unit, and supplying it as string type, instead of integer.
Budget Fields: daiyBudget and totalBudget map to budgets.daily.limitMicros and budgets.total.limitMicros respectively. dailySpent and spentBudget map to budgets.daily.spentMicros and budgets.total.spentMicros. Beware that they are now mandatory to supply. Values should be supplied in string type, instead of integer, and at micro precision, instead of cents. The budget limits can also be "UNLIMITED".
Shipping Cost: cost is renamed to costCents. The value was already in cents so there is no need for conversion.
Removed field(s): currency, allowPayPal. externalId is marked as deprecated and planned for removal, please use vendorId instead.

GET /ad/ (list)

Request payload: deprecated version

{
  "ads": [
    {
      // ...
      "statusReasons": ["DOMAIN_PENDING"],
      "priceType": "FIXED_PRICE",
      "currency": "EUR",
      "price": 5600,
      "originalPrice": 6500,
      "cpc": 15,
      "totalBudget": 1000,
      "dailyBudget": 500,
      "spentBudget": 120,
      "dailySpent": 50,
      "pageNumber": 2,
      "suggestedCpcForPageOne": 15,
      "allowPayPal": true,
      "shippingOptions": [
        {
          "cost": 500,
          "time": "2d-5d"
        }
      ]
    }
  ],
  "count": 1,
  "nextPageToken": "eyJ0eXAiOiJK"
}

Request payload: new version

{
  "ads": [
    {
      // ...
      "price": {
        "amountCents": 5600,
        "originalAmountCents": 6500,
        "priceType": "FIXED_PRICE"
      },
      "campaignId": 54212,
      "bidMicros": "10000",
      "budgets": {
        "daily": {
          "limitMicros": "UNLIMITED",
          "spentMicros": "500000"
        },
        "total": {
          "limitMicros": "10000000",
          "spentMicros": "1200000"
        }
      },
      "shippingOptions": [
        {
          "costCents": 500,
          "time": "2d-5d"
        }
      ]
    }
  ],
  "count": 1
}

Mapping details

Deprecated media type(s): application/sellside.ad.list-v4+json
New media type: application/sellside.ad.list-v5+json
Ads: the list of ads under ads is now of the v5 format.
Removed field(s): offset, paremainingBudget
New field(s): nextPageToken: this replaces the usage of offset for pagination. The value is a string that should be used as a query parameter in the next request to get the next page of results.

PUT /ad/{id}/status/{status}

Only change the media type to a versioned one application/sellside.ad-v5+json, it should be completely backwards compatible. See the FAQ section for details.

GET /categories

Response payload: deprecated version

{
  // ...
  "config": {
    // ...
    "cpc": "[1,250]",
    "totalBudget": "[100,200000000]",
    "dailyBudget": "[1000,200000000]",
    "currency": "EUR",
    "paypalEnabled": true,
    "suggestedCpcForPageOne": 30,
   }
}

Response payload: new version

{
  // ...
  "config": {
    // ...
    "bidMicros": "[10000,2500000]",
    "totalBudgetMicros": "[1000000,2000000000000]",
    "dailyBudgetMicros": "[10000000,2000000000000]"
   }
}

Mapping details

Deprecated media type(s): application/sellside.category.list-v1+json
New media type: application/sellside.category.list-v5+json
CPC: cpc is replaced by bidMicros. The interval values require conversion from a micros unit when interpreting them as cents.
Budget Fields: dailyBudget and totalBudget map to dailyBudgetMicros and totalBudgetMicros respectively. The interval values require conversion from a micros unit, when interpreting them as cents.
Removed field(s): suggestedCpcForPageOne, currency, paypalEnabled.

GET /category/{id}

Response payload: deprecated version

{
  // ...
  "config": {
    // ...
    "cpc": "[1,250]",
    "totalBudget": "[100,200000000]",
    "dailyBudget": "[1000,200000000]",
    "currency": "EUR",
    "paypalEnabled": true,
    "suggestedCpcForPageOne": 30,
   }
}

Response payload: new version

{
  // ...
  "config": {
    // ...
    "bidMicros": "[10000,2500000]",
    "totalBudgetMicros": "[1000000,2000000000000]",
    "dailyBudgetMicros": "[10000000,2000000000000]"
   }
}

Mapping details

Deprecated media type(s): application/sellside.category-v2+json
New media type: application/sellside.category-v5+json
CPC: cpc is replaced by bidMicros. The interval values require conversion from a micros unit when interpreting them as cents.
Budget Fields: dailyBudget and totalBudget map to dailyBudgetMicros and totalBudgetMicros respectively. The interval values require conversion from a micros unit, when interpreting them as cents.
Removed field(s): suggestedCpcForPageOne, currency, paypalEnabled.

Summary of API version changes

API Endpoint	Deprecated Versions	New Version
`GET /ad/{id}`	`v2`, `v3`	`v5`
`GET /ad/byVendor/{vendorId}`	`v2`, `v3`	`v5`
`POST /ad`	`v2`, `v3`	`v5`
`PUT /ad/{id}`	`v2`, `v3`	`v5`
`GET /ad/ (list)`	`v4`	`v5`
`PUT /ad/{id}/status/{status}`	unversioned	`v5`
`GET /categories`	`v1`	`v5`
`GET /category/{id}`	`v1`	`v5`

Campaigns¶

The Campaigns API helps you manage your campaign(s) efficiently. Think of a campaign as a container for ads, with key details like the campaign ID, name, creation date, and daily and total budget limits. Each campaign also has a status field that shows whether it is active or inactive.

By default, campaign management is largely automated behind the scenes. All seller ads are automatically grouped into a single default campaign that is created and managed under the hood. However, as an API partner, you have the flexibility to create, update, and manage campaigns yourself, allowing for more granular control over your advertising strategy.

An ad can only be inside one campaign at a given moment. If you want to move an ad to a different campaign, you need to update the ad with the new campaignId.

When using the campaigns API for the first time, it’s handy to remember to:

○ Get a list of campaigns to check if the user already has an automatic “default” campaign created by the system. It will provide you with a campaign identifier can then use for the rest of the endpoints.

○ Update a campaign budgets to set or change a daily and total budget for the campaign. This is a prerequisite for using the autobidding feature. Beware that the budget limits apply to all ads within the campaign, which means that when the budget limit is reached, all ads in the campaign will be taken offline.

○ You can also work with a vendorId in case you manage multiple campaigns and want to keep track of them in your own system too.

Note

The ability to manage multiple campaigns is currently only available for Kleinanzeigen sellers. Please contact our Pro team for access to the functionality of managing multiple campaigns per seller.

FAQ¶

○ What should I do with the externalId ? I need it for keeping track of ads.

Please move to using vendorId, keep in mind that it needs to be unique per seller.

○ What happened to the ad funnel information, it is no longer in the payload?

The ad funnel information is now available in the new GET /ad/{id}/position endpoint.

○ How do I handle the new bidMicros field?

The bidMicros field is a replacement for the old cpc field. It is a value in micros, which is 1/10000 of a cent. When interpreting the value, you should convert it to cents by dividing by 10000.

○ What is the new campaignId field in the ad payload?

The campaignId field is an identifier for the campaign which this ad is part of. Campaign management is optional. By default, every seller has one campaign associated with them, with every ad attached to that campaign. See Campaigns for more.

○ What does the status value DOMAIN_PENDING in ads mean?

This status is related to a phishing protection measure we implemented for sellers using the Admarkt Console UI. This protection helps prevent scammers from adding phishing URLs to ads when taking over a seller account, by requiring sellers to confirm that the domain associated with the ad is valid, via email. It’s important to note that this protection is currently only active for sellers who manage their ads through the Console UI. As a result, API partners should not typically encounter the DOMAIN_PENDING status.

○ Do I have to use the campaign related endpoints?

No, campaign management is optional. By default, every seller has one campaign associated with them, with every ad attached to that campaign. However, if you plan to leverage our autobidding features, you’ll need to use the campaign-related endpoints, specifically to set a daily budget limit at the campaign level. This is a prerequisite for using the autobidding. Setting a daily limit also helps you optimize your cost per click and maximize conversions while controlling your budget from being depleted too quickly.

○ What happens when I pause a campaign?

When you set the status of a campaign to PAUSED, all ads within that campaign will no longer be visible online on our marketplace, and your budget will immediately stop spending. However, this does not change the individual status of each ad; it only affects their effective visibility for the buyers on our marketplace. When you reactivate the campaign by setting its status to ACTIVE or by adding a budget, only the ads with an individual status of ACTIVE will become visible on our marketplace again.