Topsort

Topsort Endpoints API Reference (2.0.0)

Download OpenAPI specification:Download

E-mail: wicha@topsort.com License: Apache 2.0

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.

Auctions

An auction determines which products should be promoted based on the vendors' bids.

Create new auctions

SecurityBearerAuth
Request
Request Body schema: 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.

required
Array of SponsoredListingsAuction (object) or BannersAuction (object) (AuctionRequest) [ 1 .. 5 ] 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.

400

HTTP status codes as registered with IANA.

401

Access token is missing or invalid

402

A monthly invoice has been issued and payment is late

post/auctions
Request samples
application/json
{
  • "auctions": [
    ]
}
Response samples
application/json
{
  • "results": [
    ]
}

Events (Beta)

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.

Report events

SecurityBearerAuth
Request
Request Body schema: application/json

Use the /events endpoint to notify Topsort about significant consumer interactions on the marketplace app:

  • Impressions — a set of impressions means such promotables have become visible to the consumer.
  • Clicks — a click is sent to Topsort when the consumer has clicked on a promotable.
  • Purchases — a purchase is sent to Topsort once a consumer places an order.

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.

non-empty
Array of objects (Impression) [ 1 .. 50 ] items
Array of objects (Click) [ 1 .. 50 ] items
Array of objects (Purchase) [ 1 .. 50 ] items
Responses
204

All events were reported successfully.

400

HTTP status codes as registered with IANA.

401

Access token is missing or invalid

post/events
Request samples
application/json
{
  • "impressions": [
    ],
  • "clicks": [
    ],
  • "purchases": [
    ]
}
Response samples
application/json
{}

All Models

AssetSource

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.

{}

Auction (Banners)

Describes the intent of running a banner ads auction.

  • For Homepage 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.
type
required
string

Discriminator for the type of auction.

Value: "banners"
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.

Enum: "desktop" "mobile"
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": {
    }
}

Auction (Sponsored Listings)

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.

Value: "listings"
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": {
    },
  • "geoTargeting": {
    }
}

Auction Result (Banners)

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": [
    ],
  • "error": false
}

Auction Result (Sponsored Listings)

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": [
    ],
  • "error": false
}

Category

One of:

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"
}

Category Disjunction

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.

Array (non-empty)
string >= 1

A category ID.

[
  • "string"
]

Click

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 resolvedBidId field received from the /auctions request.

object (Entity)

The entity associated with the promotable over which the interaction occurred. It will be ignored if resolvedBidId is not blank.

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": {
    },
  • "placement": {
    },
  • "occurredAt": "2009-01-01T12:59:59-05:00",
  • "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
  • "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2"
}

Error

errCode
required
string

A short string uniquely identifying the problem.

Enum: "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
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.

{}

Events Request

Array of objects (Impression) [ 1 .. 50 ] items
Array of objects (Click) [ 1 .. 50 ] items
Array of objects (Purchase) [ 1 .. 50 ] items
{
  • "impressions": [
    ],
  • "clicks": [
    ],
  • "purchases": [
    ]
}

Geotargeting

An object describing geographical information associated with this auction.

location
required
string

The location this auction is being run for.

{
  • "location": "string"
}

Impression

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 resolvedBidId field received from the /auctions request.

object (Entity)

The entity associated with the promotable over which the interaction occurred. It will be ignored if resolvedBidId is not blank.

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": {
    },
  • "placement": {
    },
  • "occurredAt": "2009-01-01T12:59:59-05:00",
  • "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
  • "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c"
}

Products

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 array and that the values must be between 0 and 1.

{
  • "ids": [
    ],
  • "qualityScores": [
    ]
}

Purchase

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": [
    ],
  • "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0"
}

Purchase Item

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
}

Winner (Banners)

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.

Enum: "product" "vendor" "brand" "url"
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=",
  • "asset": []
}

Winner (Sponsored Listings)

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.

Enum: "product" "vendor" "brand" "url"
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="
}