Release Notes

This section gives insight on what our current and previous releases contain.

Feb 2023: ‘Campaigns & Micros’

Synopsis

• changing wording of cpc to bid, Functionality has not changed.

• For bid, budgets & spent values we now communicate in micros: 1 cent == 10000 micros. Fields representing a monetary value will now also be named accordingly, mentioning whether they represent a value in cents or micros. This will result in fields like bidMicros and amountCents. The change into micros is also represented in the category data, where the interval of allowed values is defined.

• Introduced campaigns, campaign ID not (yet) mandatory while placing ads. Campaigns have their own daily/total budgets. Since currently only 1 campaign is allowed per user, the budgets from this campaign effectively act on all ads.

• Moved price and related fields into a struct.

Removed Fields

• removed externalID, use vendorID instead.

• removed currency, 1 country == 1 currency anyway. Monetary values always in local currency.

• removed pageNumber & suggestedCpcForPageOne: In the desktop-era the majority of traffic was generated by leaf category browse actions, which lead to the introduction of the “suggested cpc for page one”. Today, traffic from additional sources like search actions and personal recommendations have become dominant. As these traffic sources use different ranking methods, the relevance of the “suggested cpc for page one” has diminished.

• Use the V2 version of /metrics/ads and /metrics/report to get spent and bid values in micros too, to avoid confusion. V1 is deprecated.

• User endpoint updated to V4, this adds 1 new field to V3 (which added 1 field to V2). Older versions than V4 are deprecated.

Ads

See Advertisements for full details.

Field	Change synopsis
cpc	moved to bidMicros. Now allows for ‘AUTOMATIC’ too.
totalBudget	moved to budgets.total.limitMicros. Now allows ‘UNLIMITED’ too.
spentBudget	moved to budgets.total.spentMicros
dailyBudget	moved to budgets.daily.limitMicros. Now allows ‘UNLIMITED’ too.
dailySpent	moved to budgets.daily.spentMicros
campaignId	new, not yet mandatory.
status	can now contain “DOMAIN_PENDING”, requiring the seller to confirm the new clickout url domain before the can go active.
price	moved to price.amountCents
priceType	moved to price.priceType
priceUnit	moved to price.priceUnit
originalPrice	moved to price.originalAmountCents
currency	removed
externalId	removed
statusReasons	removed, status is expanded
pageNumber	removed
suggestedCpcForPageOne	removed
allowPaypal	removed

Categories

See Categories for full details.

Field	Change synopsis
currency	removed
cpc	moved to bidMicros.
totalBudget	moved to totalBudgetMicros.
minDailyBudget	moved to dailyBudgetMicros. This is now an interval instead of min value.
paypalEnabled	removed
paypalBpEnabled	removed
suggestedCpcForPageOne	removed

Campaigns

Added first campaign support. See Campaigns for full details.

• GET /campaigns to get list of campaigns for a user. Expected 0 or 1 result.

• GET /campaign/{id} to fetch the individual campaign.

• POST /campaign to create a campaign. Currently only 1 allowed per seller.

• PUT /campaign/{id} to update the campaign. Currently only status & budgets can be updated.

• PUT /campaign/{id}/status/{status} to manage the campaign status (ACTIVE,PAUSED) directly.

• PUT /campaign/{id}/budgets to manage the campaign’s budgets directly.

Note

For the time being, we will create a campaign underwater for users who start placing ads without first having created a campaign. All subsequent ads will belong to that default campaign. Be sure to check the budgets of that campaign as a default campaign will have unlimited budget. Deleting a campaign is currently not allowed.

User

See GET /user for full details.

Start using V4. There are 2 new fields in comparison with V2: hasAds (bool), whether a user has ads in the system and isApiManaged (bool), whether we see API partners managing ads for the user (not true if an api partner is using RO scopes only)

Deprecation list

The following calls are deprecated and scheduled to be removed on May 1st, 2023:

deprecated endpoint	replaced by
GET /ad v4	GET /ad v5
GET /ad/{id} v3	GET /ad/{id} v5
GET /ad/{id} v2	GET /ad/{id} v5
GET /ad/byVendor/{vendorId} v3	GET /ad/byVendor/{vendorId} v5
GET /ad/byVendor/{vendorId} v2	GET /ad/byVendor/{vendorId} v5
POST /ad v3	POST /ad/ v5
POST /ad v2	POST /ad/ v5
PUT /ad/{id} v3	PUT /ad/{id} v5
PUT /ad/{id} v2	PUT /ad/{id} v5
GET /user v2	GET /user v4
GET /user v3	GET /user v4
GET /category/{id} v2	GET /category/{id} v5
GET /categories V1	GET /categories V5