Topsort

Topsort Endpoints API Reference (1.0.1)

Download OpenAPI specification:Download

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

Authentication

BearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Auctions

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

Creates a new auction

Request
Security:
BearerAuth
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.

Any of:

Multiple different slot types may be combined into a single request.

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.

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

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

Request
Security:
BearerAuth
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.

eventType
required
string

Discriminator for the type of event.

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
{
  • "id": "234f678-f90c",
  • "clickId": "c_k37sdm",
  • "impressions": [
    ],
  • "purchaseId": "p_k39abc"
}

All Models

Auction

object
{
  • "slots": {
    }
}

Auction Request (Full Definition)

Any of:

Multiple different slot types may be combined into a single request.

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.

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

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.

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

Banner Options

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

Banners Slots

bannerAds
integer >= 1
{
  • "bannerAds": 2
}

Click Event

eventType
required
string

Discriminator for the type of event.

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": "ClickEvent",
  • "session": {
    },
  • "placement": {
    },
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

Event

eventType
required
string

Discriminator for the type of event.

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": "ClickEvent",
  • "session": {
    },
  • "placement": {
    },
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

Event Response

id
string
clickId
string
Array of objects (ImpressionResponse)
purchaseId
string
{
  • "id": "234f678-f90c",
  • "clickId": "c_k37sdm",
  • "impressions": [
    ],
  • "purchaseId": "p_k39abc"
}

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

eventType
required
string

Discriminator for the type of event.

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": "ClickEvent",
  • "session": {
    },
  • "placement": {
    },
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

Impression Response

id
string
impressionId
string
{
  • "id": "234f678-f90c",
  • "impressionId": "i_k31xyz"
}

Listings Slots

listings
integer >= 1
{
  • "listings": 2
}

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

eventType
required
string

Discriminator for the type of event.

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": "ClickEvent",
  • "session": {
    },
  • "placement": {
    },
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}

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

Session

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

Topsort Error

errCode
required
string
Enum: "bad_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" "too_few_impressions" "too_few_slots"
docUrl
any
Value: "https://topsort-api.redoc.ly"
message
string
{}

Vendor

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

Winner

rank
required
integer >= 0

Where the product's bid ranked in the auction. Zero-based, so the product with rank 0 won the auction and had the highest bid. 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": 0,
  • "productId": "pSA0238",
  • "winnerType": "product",
  • "winnerId": "b_Mfk15",
  • "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
  • "assetUrl": "https://address.to/image.png"
}