Create sponsored brand auctions

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The information describing what will be auctioned. Topsort will run an auction for each batched auction request, for which products' bids will compete against each other.

auctions

object[]

required

Show child attributes

auctions.winners

integer

required

Specifies the maximum number of auction winners that should be returned.

Required range: x > 1

auctions.placementId

string

required

auctions.triggers

object

required

Show child attributes

auctions.triggers.category

object

A category for the purpose of running an auction.

Show child attributes

auctions.triggers.category.id

string

required

The category ID of the bids that will participate in an auction.

Minimum length: 1

auctions.triggers.products

object

Show child attributes

auctions.triggers.products.ids

string[]

required

An array of product IDs that should participate in the auction. We recommend sending no more than 500 products per auction.

auctions.triggers.products.qualityScores

number[]

An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. If given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products. Note that the length of this array must be the same as the length of the ids array and that the values must be between 0 and 1.

Response

201

application/json

The auction results. The list of winners will contain at most `winners` entries per auction. It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc.

results

object[]

required

Show child attributes

results.winners

object[]

required

Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error.

Show child attributes

results.winners.rank

integer

required

Where the product's bid ranked in the auction. One-based, so the product with rank 1 won the auction. In an auction response, the winners array is sorted so rank will match the entry's index.

Required range: x > 1

results.winners.productId

string

required

The marketplace's ID of the winning entity, depending on the target of the campaign.

results.winners.resolvedBidId

string

required

An opaque Topsort ID to be used when this item is interacted with.

results.winners.assets

object[]

required

Assets used to render the sponsored brand ad.

Show child attributes

results.winners.assets.url

string

A vendor provided asset that the marketplace has to render. The asset will be served by Topsort's CDN.

results.winners.assets.role

string

The role of the asset. It can be either logo or image.

results.winners.assets.contentType

string

The asset MIME type.

results.winners.assets.contentLength

integer

The size of the asset in bytes.

results.winners.assets.width

integer

The asset width in pixels.

results.winners.assets.height

integer

The asset height in pixels.

results.winners.title

string

An optional title for the sponsored brand selected when creating the campaign.

results.error

boolean

required

A boolean indicating whether this auction was resolved successfully.