Create auctions

POST

/auctions

• Auctions v2 path

Authentication

Topsort’s APIs are authenticated via bearer tokens. Requests must include an authorization header containing your private API key.

Don't have an API key yet? Learn how to generate one.

Authorization

required

string

The header containing a private API key. Format this header as follows:

Authorization: Bearer <YOUR-API-KEY>

Request Body

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.

application/json

object

auctions

required

Array

>= 1 items <= 5 items

One of:

object

Describes the intent of running a sponsored listings auction.

Exactly one of the following fields must be set:

• products
• category

object

type

required

Discriminator for the type of auction.

string

Allowed values: listings

slots

required

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

integer format: int32

>= 1

category

One of:

Single Category

A category for the purpose of running an auction.

object

id

required

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

string

>= 1 characters

Multiple Categories

A set of categories for the purpose of running an auction.

object

ids

required

An array containing the category IDs of the bids that will participate in an auction. In order to participate in an auction, a bid product must belong to all of the categories provided in the auction request.

Array<string>

>= 1 items

Category Disjunctions

Multiple disjunctions of categories for the purpose of running an auction.

object

disjunctions

required

An array of disjunctions.

In order to participate in an auction, a bid product must belong to at least one of the categories for each of the disjunctions provided in the auction request.

Array<Array<string>>

>= 1 items <= 5 items

searchQuery

The search string provided by a user.

string

products

object

ids

required

An array of product IDs that should participate in the auction.

Array<string>

>= 1 items <= 10000 items

qualityScores

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.

Array<number>

>= 1 items <= 10000 items

geoTargeting

An object describing geographical information associated with this auction.

object

location

required

The location this auction is being run for.

string

object

Describes the intent of running a banner ads auction.

• For Landing Page banners, category and searchQuery must be empty.
• For Category banners, the category field must be set.
• For Keywords banners, the searchQuery field must be set.

object

type

required

Discriminator for the type of auction.

string

Allowed values: banners

slots

required

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

integer format: int32

>= 1

category

One of:

Single Category

A category for the purpose of running an auction.

object

id

required

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

string

>= 1 characters

Multiple Categories

A set of categories for the purpose of running an auction.

object

ids

required

An array containing the category IDs of the bids that will participate in an auction. In order to participate in an auction, a bid product must belong to all of the categories provided in the auction request.

Array<string>

>= 1 items

Category Disjunctions

Multiple disjunctions of categories for the purpose of running an auction.

object

disjunctions

required

An array of disjunctions.

In order to participate in an auction, a bid product must belong to at least one of the categories for each of the disjunctions provided in the auction request.

Array<Array<string>>

>= 1 items <= 5 items

searchQuery

The search string provided by a user.

string

device

The device for which the ads are meant for.

string

default: desktop

Allowed values: desktop mobile

geoTargeting

An object describing geographical information associated with this auction.

object

location

required

The location this auction is being run for.

string

slotId

required

The ID of the banner placement for which this auction will be run for.

string

>= 1 characters

products

object

ids

required

An array of product IDs that should participate in the auction.

Array<string>

>= 1 items <= 10000 items

qualityScores

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.

Array<number>

>= 1 items <= 10000 items

Responses

201

The auction results. The list of winners will contain at most slots 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.

application/json

object

results

required

Array

>= 1 items <= 5 items

One of: discriminator: resultType

object

object

resultType

required

string

winners

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.

Array<object>

object

rank

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.

integer format: int32

>= 1

type

required

The target type of the winning bid.

string

Allowed values: product vendor brand url

id

required

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

string

resolvedBidId

required

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

string

error

required

A boolean indicating whether this auction was resolved successfully.

boolean

object

object

resultType

required

string

winners

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.

Array<object>

object

rank

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.

integer format: int32

>= 1

type

required

The target type of the winning bid.

string

Allowed values: product vendor brand url

id

required

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

string

resolvedBidId

required

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

string

asset

required

The list of available sources for a banner.

Array<object>

>= 1 items

A source available for an asset (banner or video).

object

url

required

A vendor provided asset that the marketplace has to use as a banner. The asset will be served by Topsort’s CDN.

string format: uri

error

required

A boolean indicating whether this auction was resolved successfully.

boolean

400

HTTP status codes as registered with IANA.

application/json

object

errCode

required

A short string uniquely identifying the problem.

string

Allowed values: bad_request empty_request internal_server_error invalid_api_key invalid_auction_id invalid_event_type invalid_promotion_type invalid_session missing_auctions missing_context missing_placement missing_product_id missing_promotion_type missing_purchased_at missing_session missing_slot_id missing_slots no_products no_purchase_items purchase_item_quantity_less_or_equal_than_zero resolved_bid_id_not_found too_few_impressions too_few_slots too_many_auctions

docUrl

A link to a documentation page providing more information about the error.

string format: uri

message

Human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field.

string

401

Access token is missing or invalid