Auction examples
- Running auctions
- Sponsored listings
- Sponsored banners
- Sponsored brands
Asset examples
Webhook examples
Assets API
Audience API
Billing API
Campaign API
- GETGet Campaigns
- POSTCreate Campaign
- GETGet Campaign By Id
- DELDelete Campaign By Id
- PATCHUpdate Campaign By Id
- GETGet Campaign Bids
- POSTCreate Campaign Bids
- DELDelete Campaign Bid By Id
- PATCHUpdate Campaign Bid By Id
- POST[BETA] Get estimated clicks of a future campaign for a given vendor
- GETGet Products In Campaign
- GETGet Sponsored Products
Catalog API
Invitation API
Modal API
Reporting API
Create auctions
Use the /auctions endpoint to create auctions. Each batch of auction requests can be a combination of
sponsored listing auctions and banner auctions. Each auction type has a unique body schemas.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Specifies the maximum number of auction winners that should be returned.
x > 1Discriminator for the type of auction.
listings A category for the purpose of running an auction.
The category ID of the bids that will participate in an auction.
1An object describing geographical information associated with this auction.
The location this auction is being run for.
The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests.
The marketplace's ID of the placement where the ad will appear.
An array of product IDs that should participate in the auction. We recommend sending no more than 500 products per auction.
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.
The search string provided by a user.
Response
A boolean indicating whether this auction was resolved successfully.
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.
The ID of the campaign that won the auction.
The marketplace's ID of the winning entity, depending on the target of the campaign.
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.
x > 1An opaque Topsort ID to be used when this item is interacted with.
The target type of the winning bid.
product, vendor, brand, url