Topsort Endpoints API Reference (1.0.1)

Download OpenAPI specification:Download

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

Auctions

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

Creates a new auction

SecurityBearerAuth
Request
Request Body schema: application/json

The information describing what will be auctioned. Topsort will run an auction for each slot type, for which products and/or vendors' bids will compete against each other. The products and vendors that will participate are also included in the request. Multiple different slot types may be combined into a single request.

Any of:
required
object (ListingsSlots)

The Slots object specifies how many auctions winners should be returned for each promotion type. The promotion types depend on the marketplace configuration. For sponsored listings, use the "listings" key.

required
Array of objects (Product)

An array of objects, each describing a product that should participate in the auction.

object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

object (GeoTargeting)

An object describing geographical information associated with this auction.

Responses
201

The auction results. The list of Winner objects will contain at most slots entries. It may contain fewer or no entries at all if there aren't enough products with usable bids. Bid 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
{
  • "slots": {
    },
  • "products": [
    ],
  • "vendors": [
    ],
  • "bannerOptions": {
    }
}
Response samples
application/json
{
  • "slots": {
    }
}

Events

Significant consumer interactions on the e-commerce site.

Report an event

SecurityBearerAuth
Request
Request Body schema: application/json

Use the /events endpoint to notify Topsort about significant consumer interactions on the e-commerce site: impressions -- product links become visible to the consumer; clicks -- the consumer clicks on a product link; and purchases -- the consumer buys some products.

One of:

A product has become visible to the consumer. In case you cannot send the impression when the product is 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 allow them to better predict their campaigns.

eventType
required
string

Discriminator for the type of event.

Value: "Impression"
required
object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

required
Array of objects (Impression) non-empty
occurredAt
string <date-time>

RFC3339 formatted timestamp including UTC offset

Responses
200

An object containing the markeplace ID for the event and the Topsort ID for the same event. Logging this can facilitate debugging. The field name for the TopsortID will be "impressionID", "clickId" or "purchaseId" depending on the event in the request.

400

HTTP status codes as registered with IANA.

401

Access token is missing or invalid

post/events
Request samples
application/json
{
  • "eventType": "Impression",
  • "session": {
    },
  • "impressions": [
    ]
}
Response samples
application/json
{
  • "impressions": [
    ]
}

All Models

Auction

object
{
  • "slots": {
    }
}

Auction Request (General Banners)

required
object (BannersSlots)

The Slots object specifies how many auctions winners should be returned for each promotion type. The promotion types depend on the marketplace configuration. For banner ads, use the "bannerAds" key.

required
Array of objects (Product)

An array of objects, each describing a product that should participate in the auction.

required
Array of objects (Vendor)

An array of objects, each describing a vendor that should participate in the auction.

object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

required
object (BannerOptions)

The BannerOptions object specifies options to take into consideration when running a banner auction.

{
  • "slots": {
    },
  • "products": [
    ],
  • "vendors": [
    ],
  • "session": {
    },
  • "bannerOptions": {
    }
}

Auction Request (Homepage Standalone Banners)

required
object (BannersSlots)

The Slots object specifies how many auctions winners should be returned for each promotion type. The promotion types depend on the marketplace configuration. For banner ads, use the "bannerAds" key.

object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

required
object
{
  • "slots": {
    },
  • "session": {
    },
  • "bannerOptions": {
    }
}

Auction Request (Sponsored Listings)

required
object (ListingsSlots)

The Slots object specifies how many auctions winners should be returned for each promotion type. The promotion types depend on the marketplace configuration. For sponsored listings, use the "listings" key.

required
Array of objects (Product)

An array of objects, each describing a product that should participate in the auction.

object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

object (GeoTargeting)

An object describing geographical information associated with this auction.

{
  • "slots": {
    },
  • "products": [
    ],
  • "session": {
    },
  • "geoTargeting": {
    }
}

Banner Options

The BannerOptions object specifies options to take into consideration when running a banner auction.

placement
string
Enum: "Home-page" "Category-page" "Search-page"
{
  • "placement": "Home-page"
}

Click Event

ClickEvents are sent to Topsort when the consumer has clicked on an impression. Topsort charges the vendor and pays the marketplace for clicks on impressions in promoted placements on the e-commerce site.

eventType
required
string

Discriminator for the type of event.

Value: "Click"
required
object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

required
object (Placement)
productId
string

The product that was clicked.

auctionId
string

Required for promoted products. Must be the ID for the auction the product won.

id
string

The marketplace's unique ID for the click.

occurredAt
string <date-time>

RFC3339 formatted timestamp including UTC offset

resolvedBidId
string
{
  • "eventType": "Click",
  • "session": {
    },
  • "placement": {
    },
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

Click Response

clickId
required
string

Topsort assigned ID for the click.

id
string

The marketplace's ID for the click, if provided.

{
  • "clickId": "00b55a66-a221-4cdd-8c76-8e422558f1c3",
  • "id": "234f678-f90c"
}

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_placement" "missing_product_id" "missing_promotion_type" "missing_purchased_at" "missing_session" "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"
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.

{}

Geotargeting

An object describing geographical information associated with this auction.

location
required
string

The location this banner is being run for.

{
  • "location": "string"
}

Impression

required
object (Placement)
productId
string

The product that was rendered.

auctionId
string

Required for promoted products. Must be the ID for the auction the product won.

id
string

The marketplace's ID for the impression.

resolvedBidId
string
{
  • "placement": {
    },
  • "productId": "p_SA0238",
  • "auctionId": "AKFU78",
  • "id": "234f678-f90c",
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

Impression Event

A product has become visible to the consumer. In case you cannot send the impression when the product is 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 allow them to better predict their campaigns.

eventType
required
string

Discriminator for the type of event.

Value: "Impression"
required
object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

required
Array of objects (Impression) non-empty
occurredAt
string <date-time>

RFC3339 formatted timestamp including UTC offset

{
  • "eventType": "Impression",
  • "session": {
    },
  • "impressions": [
    ],
  • "occurredAt": "2022-01-23T12:34:56-05:00"
}

Impressions Response

Array of objects (ImpressionResponse)

The collection of all impressions that were processed correctly.

{
  • "impressions": [
    ]
}

Placement

page
required
string

A marketplace assigned name for a page.

location
string

A marketplace defined name for a page part.

{
  • "page": "search_results",
  • "location": "position_1"
}

Product

productId
required
string <string>
quality
number <float> [ 0 .. 1 ]
{
  • "productId": "p_SA0238",
  • "quality": 0.75
}

Purchase Event

The consumer has purchased some products.

eventType
required
string

Discriminator for the type of event.

Value: "Purchase"
required
object (Session)

The Session object allows correlating user activity during a session whether or not they are actually logged in.

id
required
string

The marketplace assigned ID for the order.

purchasedAt
required
string <date-time>

RFC3339 formatted timestamp including UTC offset

required
Array of objects (PurchaseItem) non-empty

Items purchased.

{
  • "eventType": "Purchase",
  • "session": {
    },
  • "id": "o:567-123",
  • "purchasedAt": "2021-10-12T07:20:50.52Z",
  • "items": [
    ]
}

Purchase Item

productId
required
string

The marketplace ID of the product being purchased.

auctionId
string

If known, the product's auction ID if the consumer clicked on a promoted link before purchasing.

quantity
integer >= 1
Default: 1

Count of product purchased.

unitPrice
required
integer >= 1

The price of a single item in minor currency units. For example, in the US (currency code "USD") the unit price is specified in cents.

resolvedBidId
string
{
  • "productId": "p_SA0238",
  • "unitPrice": 1295,
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

Purchase Response

purchaseId
required
string

Topsort assigned ID for the purchase.

id
string

The marketplace's ID for the purchase, if provided.

{
  • "purchaseId": "3f15c9a5-5129-4359-b39c-099e273afe66",
  • "id": "234f678-f90c"
}

Session

The Session object allows correlating user activity during a session whether or not they are actually logged in.

sessionId
required
string

Long-lived token identifying the customer interacting with the marketplace. 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.

{
  • "sessionId": "ebeaf802-6d0a-41a3-ae59-661887c4f6cb"
}

Vendor

vendorId
required
string <string>
{
  • "vendorId": "v_89kjm"
}

Winner

rank
required
integer >= 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.

productId
required
string

The marketplace's ID for the product. It will match the ID for a product in the request's products array.

winnerType
string

The type of the winning bid, depending on the campaign. It can be product or vendor.

Enum: "product" "vendor"
winnerId
string

The marketplace's ID of the winnning item, depending on the campaign.

resolvedBidId
string

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

assetUrl
string

The vendor defined asset that the marketplace has to use as a banner.

{
  • "rank": 1,
  • "productId": "pSA0238",
  • "winnerType": "product",
  • "winnerId": "b_Mfk15",
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
}