Download OpenAPI specification:Download
In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the /v2/auctions
and /v2/events
endpoints must be integrated. Below are the endpoint and model definitions for each.
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.
required | Array of SponsoredListingsAuction (object) or BannersAuction (object) (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": 1,
- "category": {
- "disjunctions": [
- [
- "c_large",
- "c_medium"
], - [
- "c_red",
- "c_blue"
]
]
}
}, - {
- "type": "listings",
- "slots": 2,
- "products": {
- "ids": [
- "p_PJbnN",
- "p_ojng4",
- "p_8VKDt",
- "p_Mfk15"
]
}, - "geoTargeting": {
- "location": "New York"
}
}, - {
- "type": "banners",
- "slots": 1,
- "slotId": "categories-ribbon-banner",
- "category": {
- "id": "c_yogurt"
}
}, - {
- "type": "banners",
- "slots": 1,
- "slotId": "homepage-banner"
}
]
}
{- "results": [
- {
- "winners": [
- {
- "rank": 1,
- "type": "product",
- "id": "p_Mfk11",
- "resolvedBidId": "WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
}
], - "error": false
}, - {
- "winners": [
- {
- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}, - {
- "rank": 2,
- "type": "product",
- "id": "p_PJbnN",
- "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "error": false
}, - {
- "winners": [
- {
- "rank": 1,
- "type": "product",
- "id": "p_PJbnN",
- "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
}
], - "error": false
}, - {
- "winners": [ ],
- "error": false
}
]
}
The specification details, particularly around placement data, may change in the short term. If this is not acceptable for your integration, please use Events V1 as an alternative.
Significant consumer interactions on the marketplace app.
Use the /events
endpoint to notify Topsort about significant consumer interactions on the marketplace app:
For promoted interactions, include the resolvedBidId
field from the /v2/auctions
response.
For unpromoted interactions, include the entity
field to describe what was interacted with.
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
{- "impressions": [
- {
- "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c",
- "occurredAt": "2019-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "categoryId": "9BLIe"
}, - "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "clicks": [
- {
- "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2",
- "occurredAt": "2019-01-01T13:01:42-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "categoryId": "9BLIe"
}, - "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "purchases": [
- {
- "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0",
- "items": [
- {
- "productId": "p_SA0238",
- "unitPrice": 12.95,
- "quantity": 2
}, - {
- "productId": "p_oajf2D",
- "unitPrice": 1.49
}
], - "occurredAt": "2019-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8"
}
]
}
{- "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. |
{
}
Describes the intent of running a banner ads auction.
category
and searchQuery
must be empty.category
field must be set.searchQuery
field must be set.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. |
Single Category (object) or Multiple Categories (object) or Category Disjunctions (object) (Category) | |
searchQuery | string The search string provided by a user. |
device | string (Device) Default: "desktop" The device for which the ads are meant for. |
object (GeoTargeting) An object describing geographical information associated with this auction. | |
slotId required | string non-empty The ID of the banner placement for which this auction will be run for. |
object (Products) |
{- "type": "banners",
- "slots": 1,
- "slotId": "categories-ribbon-banner",
- "category": {
- "id": "c_yogurt"
}
}
Describes the intent of running a sponsored listings auction.
Exactly one of the following fields must be set:
products
category
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. |
Single Category (object) or Multiple Categories (object) or Category Disjunctions (object) (Category) | |
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"
}
}
resultType required | string |
required | Array of objects (BannersWinner) 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. |
{- "resultType": "string",
- "winners": [
- {
- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
}
], - "error": false
}
resultType required | string |
required | Array of objects (SponsoredListingsWinner) 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. |
{- "resultType": "string",
- "winners": [
- {
- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "error": false
}
A category for the purpose of running an auction.
id required | string non-empty The category ID of the bids that will participate in an auction. |
{- "id": "c_yogurt"
}
An array of category IDs, describing a category disjunction.
A bid entity must belong to at least one of the categories in the disjunction in order to participate in the auction.
A category ID.
[- "string"
]
A click is sent to Topsort when the consumer has clicked on a promotable. For promoted entities, include the resolvedBidId
field from the /v2/auctions
response. For unpromoted entities, include the entity
field to describe what was clicked. 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 (Entity) The entity associated with the promotable over which the interaction occurred. It will be ignored if | |
object (Placement) | |
occurredAt required | string <date-time> RFC3339 formatted timestamp including UTC offset. |
opaqueUserId required | string non-empty The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases. If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year. |
id required | string non-empty 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=",
- "entity": {
- "id": "string",
- "type": "product"
}, - "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "productId": "string",
- "categoryIds": [
- "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": [
- {
- "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c",
- "occurredAt": "2019-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "categoryId": "9BLIe"
}, - "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "clicks": [
- {
- "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2",
- "occurredAt": "2019-01-01T13:01:42-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
- "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "categoryId": "9BLIe"
}, - "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
], - "purchases": [
- {
- "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0",
- "items": [
- {
- "productId": "p_SA0238",
- "unitPrice": 12.95,
- "quantity": 2
}, - {
- "productId": "p_oajf2D",
- "unitPrice": 1.49
}
], - "occurredAt": "2019-01-01T12:59:59-05:00",
- "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8"
}
]
}
An object describing geographical information associated with this auction.
location required | string The location this auction is being run for. |
{- "location": "string"
}
An impression means a promotable has become visible to the consumer. For promoted entities, include the resolvedBidId
field from the /v2/auctions
response. For unpromoted entities, include the entity
field to describe what was seen. 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 (Entity) The entity associated with the promotable over which the interaction occurred. It will be ignored if | |
object (Placement) | |
occurredAt required | string <date-time> RFC3339 formatted timestamp including UTC offset. |
opaqueUserId required | string non-empty The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases. If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year. |
id required | string non-empty 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=",
- "entity": {
- "id": "string",
- "type": "product"
}, - "placement": {
- "path": "/categories/dairy",
- "position": 1,
- "page": 1,
- "pageSize": 15,
- "productId": "string",
- "categoryIds": [
- "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. |
qualityScores | 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"
], - "qualityScores": [
- 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 non-empty The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases. If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year. |
required | Array of objects (PurchaseItem) non-empty Items purchased. |
id required | string non-empty 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 needs to be 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 non-empty The marketplace ID of the product being purchased. |
quantity | integer >= 1 Default: 1 Count of products purchased. |
unitPrice required | number <double> > 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 target type of the winning bid. |
id required | string The marketplace's ID of the winning entity, depending on the target of the campaign. |
resolvedBidId required | string An opaque Topsort ID to be used when this item is interacted with. |
required | Array of objects (AssetSource) non-empty The list of available sources for a banner. |
{- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
}
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 target type of the winning bid. |
id required | string The marketplace's ID of the winning entity, depending on the target of the campaign. |
resolvedBidId required | string An opaque Topsort ID to be used when this item is interacted with. |
{- "rank": 1,
- "type": "product",
- "id": "p_Mfk15",
- "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}