Download OpenAPI specification:Download
The information describing what will be auctioned. Topsort will run an auction for each batched auction request, for which products, brands and/or vendors' bids will compete against each other. Provided fields are additive, in the sense that only bids that match all filtering fields are considered (e.g. in the example below, only bids for products in the c_yogurt category that match the "Noosa Peach" search string will participate in the acution).
required | Array of any (AuctionRequest) [ 1 .. 5 ] items |
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.
HTTP status codes as registered with IANA.
Access token is missing or invalid
A monthly invoice has been issued and payment is late
{- "auctions": [
- {
- "type": "listings",
- "slots": 2,
- "products": {
- "ids": [
- "p_PJbnN",
- "p_ojng4",
- "p_8VKDt",
- "p_Mfk15"
]
}, - "geoTargeting": {
- "location": "New York"
}
}, - {
- "type": "banners",
- "slots": 1,
- "aspectRatio": "4:1",
- "category": {
- "id": "c_yogurt"
}
}, - {
- "type": "banners",
- "slots": 1,
- "aspectRatio": "3:2",
- "searchQuery": "Noosa Peach"
}
]
}
{- "results": [
- {
- "winners": [
- {
- "rank": 1,
- "winnerType": "product",
- "winnerId": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}, - {
- "rank": 2,
- "winnerType": "product",
- "winnerId": "p_PJbnN",
- "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "error": false
}, - {
- "winners": [
- {
- "rank": 1,
- "winnerType": "product",
- "winnerId": "p_PJbnN",
- "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
}
], - "error": false
}
]
}
Use the /events
endpoint to notify Topsort about significant consumer interactions on the marketplace app: impressions — ad promotions become visible to the consumer; clicks — the consumer clicks on an ad promotion; and purchases — the consumer buys some products.
Array of objects (Impression) [ 1 .. 50 ] items | |
Array of objects (Click) [ 1 .. 50 ] items | |
Array of objects (Purchase) [ 1 .. 50 ] items |
All events were reported successfully.
HTTP status codes as registered with IANA.
Access token is missing or invalid
{ }
{- "errCode": "bad_request",
- "message": "string"
}
A source available for an asset (banner or video).
url required | string <uri> A vendor provided asset that the marketplace has to use as a banner. The asset will be served by Topsort's CDN. |
{
}
required | Array of objects (Winner) 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. |
error required | boolean A boolean indicating whether this auction was resolved successfully. |
{- "winners": [
- {
- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
}
], - "error": false
}
Describes the intent of running a banner ads auction. Only one field between category and searchQuery must be provided.
type required | string Discriminator for the type of auction. |
slots required | integer <int32> >= 1 Specifies the maximum number of auction winners that should be returned. |
object (Category) An object describing the category of the bids that will participate in an auction. | |
searchQuery | string The search string provided by a user. |
device | string (Device) Default: "desktop" The device for which the ads are meant for. |
aspectRatio required | string^\d+:\d+$ The aspect ratio for a specific slot for a banner placement in the marketplace app. The aspect ratio for the category (or home page, if no category ID was provided in the request) must have been previously set up in the Topsort app. |
{- "type": "banners",
- "slots": 1,
- "aspectRatio": "4:1",
- "category": {
- "id": "c_yogurt"
}
}
Describes the intent of running a sponsored listings auction. At least one of the following fields must be set: category, products.
type required | string Discriminator for the type of auction. |
slots required | integer <int32> >= 1 Specifies the maximum number of auction winners that should be returned. |
required | object (Products) |
object (GeoTargeting) An object describing geographical information associated with this auction. |
{- "type": "listings",
- "slots": 2,
- "products": {
- "ids": [
- "p_PJbnN",
- "p_ojng4",
- "p_8VKDt",
- "p_Mfk15"
]
}, - "geoTargeting": {
- "location": "New York"
}
}
An object describing the category of the bids that will participate in an auction.
id required | string The marketplace's ID of the category for which an auction will be run. |
{- "id": "c_yogurt"
}
A click is sent to Topsort when the consumer has clicked on an ad. Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app.
resolvedBidId | string If the click is over an ad promotion, this is the |
object (Placement) | |
occurredAt required | string <date-time> RFC3339 formatted timestamp including UTC offset. |
opaqueUserId required | string The opaque user ID allows correlating user activity, whether or not they are actually logged in. It must be long lived. |
id required | string The marketplace's unique ID for the click. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no click model on the marketplace side, generate a unique string that does not change if the event is resent. |
{- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "productId": "string",
- "categoryId": "string",
- "searchQuery": "string"
}, - "occurredAt": "2009-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2"
}
errCode required | string A short string uniquely identifying the problem. |
docUrl | string <uri> A link to a documentation page providing more information about the error. |
message | string 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. |
{- "errCode": "bad_request",
- "message": "string"
}
Array of objects (Impression) [ 1 .. 50 ] items | |
Array of objects (Click) [ 1 .. 50 ] items | |
Array of objects (Purchase) [ 1 .. 50 ] items |
{- "impressions": [
- {
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "productId": "string",
- "categoryId": "string",
- "searchQuery": "string"
}, - "occurredAt": "2009-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c"
}
], - "clicks": [
- {
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "productId": "string",
- "categoryId": "string",
- "searchQuery": "string"
}, - "occurredAt": "2009-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2"
}
], - "purchases": [
- {
- "occurredAt": "2021-10-12T07:20:50.52Z",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "items": [
- {
- "productId": "p_SA0238",
- "quantity": 2,
- "unitPrice": 12.95
}
], - "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0"
}
]
}
An object describing geographical information associated with this auction.
location required | string The location this banner is being run for. |
{- "location": "string"
}
An impression means an ad has become visible to the consumer. In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns.
resolvedBidId | string If the impression is over an ad promotion, this is the |
object (Placement) | |
occurredAt required | string <date-time> RFC3339 formatted timestamp including UTC offset. |
opaqueUserId required | string The opaque user ID allows correlating user activity, whether or not they are actually logged in. It must be long lived. |
id required | string The marketplace's unique ID for the impression. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no impression model on the marketplace side, generate a unique string that does not change if the event is resent. |
{- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "productId": "string",
- "categoryId": "string",
- "searchQuery": "string"
}, - "occurredAt": "2009-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c"
}
ids required | Array of strings [ 1 .. 10000 ] items An array of product IDs that should participate in the auction. |
quality_scores | Array of numbers <float> [ 1 .. 10000 ] items 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": [
- "p_SA0238"
], - "quality_scores": [
- 0.75
]
}
A purchase is sent to Topsort once a marketplace customer places an order. These events are used to measure the effectiveness of an ad campaign.
occurredAt required | string <date-time> RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was placed. |
opaqueUserId required | string The opaque user ID allows correlating user activity, whether or not they are actually logged in. It must be long lived. |
required | Array of objects (PurchaseItem) non-empty Items purchased. |
id required | string The marketplace unique ID for the order. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no unique ID for orders on the marketplace side, generate a unique string that does not change if the event is resent. |
{- "occurredAt": "2021-10-12T07:20:50.52Z",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "items": [
- {
- "productId": "p_SA0238",
- "quantity": 2,
- "unitPrice": 12.95
}
], - "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0"
}
productId required | string The marketplace ID of the product being purchased. |
quantity | integer >= 1 Default: 1 Count of products purchased. |
unitPrice required | number <float> > 0 The price of a single item in the marketplace currency. |
{- "productId": "p_SA0238",
- "quantity": 2,
- "unitPrice": 12.95
}
rank required | integer <int32> >= 1 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. |
type required | string The type of the winning bid. |
id required | string The marketplace's ID of the winning entity, depending on the campaign. |
resolvedBidId required | string An opaque Topsort ID to be used when this item is interacted with. |
Array of objects (AssetSource) non-empty The list of available sources for an asset (banner or video). |
{- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
}