Skip to content
Toposort Logo
Knowledge Base

Sponsored Brands Auction Request and Response

Sponsored Brands auctions work by sending auction requests with placement details and targeting triggers, then receiving structured responses containing winning campaigns with all necessary creative assets and metadata.

Available Templates

Sponsored Brands campaigns are built using one of three pre-built templates:

  • Product Collection: Multiple products displayed on one landing page for comprehensive product discovery
  • Store Spotlight: Drives traffic directly to a vendor’s store page for brand awareness
  • Video: Single product promoted with engaging video content for enhanced user engagement

Auction Request

Auction requests for Sponsored Brands follow the standard auction format with specific triggers for targeting:

{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "products": {
          "ids": ["pmk_1", "pmk_8"]
        },
        "category": {
          "id": "electronics"
        },
        "searchQuery": "cool electronics"
      },
      "geoTargeting": "santiago",
      "opaqueUserId": "user-123"
    }
  ]
}

Request Parameters

  • winners: Number of sponsored brands campaigns to return
  • placementId: Identifier for the sponsored brands placement slot
  • triggers: Targeting criteria using one of:
    • products.ids: Array of specific product IDs to target
    • category.id: Product category for broader targeting
    • searchQuery: Search terms for keyword-based targeting
  • geoTargeting: Geographic location for location-based campaigns
  • opaqueUserId: Anonymous user identifier for personalization

Auction Response

The auction response returns winning sponsored brands campaigns with complete creative assets and metadata:

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "resolvedBidId": "ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8",
          "productId": "pmk_1",
          "type": "product",
          "id": "pmk_1",
          "title": "Brand Example Promo 1",
          "assets": [
            {
              "url": "https://assets.hosted.topsort.com/5bcccb92e5eaaa73ce9fcc545e944865bf70e9b60e5a048979769282450343c4/example-banner-1.png",
              "role": "image",
              "contentType": "image/png",
              "contentLength": 33902,
              "width": 920,
              "height": 920
            },
            {
              "url": "https://assets.hosted.topsort.com/c27c9cd94badc90fb50827e144dfacb2f51a601560905b950f525cec725ea85f/example-logo-1.png",
              "role": "logo",
              "contentType": "image/png",
              "contentLength": 80648,
              "width": 264,
              "height": 264
            }
          ],
          "content": {
            "headline": "some cool headline",
            "brandName": "my brand",
            "creative1": "https://some.url.com/cool.jpeg"
          },
          "campaignId": "018f3ff3-0d7c-7b75-bf99-629c62c09dc3",
          "productIds": ["pmk_1", "pmk_8"]
        }
      ],
      "error": false
    }
  ]
}

Response Fields

Winner Object

  • rank: Position ranking of the winning campaign
  • resolvedBidId: Unique identifier for bid tracking and attribution
  • productId: Primary product identifier for the campaign
  • type: Campaign type (always “product” for sponsored brands)
  • id: Campaign identifier
  • title: Campaign title for display purposes
  • campaignId: UUID of the sponsored brands campaign
  • productIds: Array of all products included in the campaign (1-5 products)

Assets Array

Creative assets for rendering the sponsored brands ad:

  • url: CDN URL for the asset
  • role: Asset type (“image” for banner creative, “logo” for brand logo)
  • contentType: MIME type of the asset
  • contentLength: File size in bytes
  • width/height: Asset dimensions in pixels

Content Object

Campaign content for rendering:

  • headline: Campaign headline text
  • brandName: Brand or vendor name
  • creative1: Additional creative asset URL (videos, secondary images)

Implementation Notes

Rendering Flexibility

The creative assets, headline, and productIds are returned separately in the auction response, allowing you to render these elements according to your frontend design requirements. The assets array contains all necessary creative components with clear role identification.

Multi-Product Support

Sponsored brands campaigns can promote 1-5 products simultaneously. The productIds array contains all products included in the campaign, while productId represents the primary product for tracking purposes.

Template Integration

While campaigns are built using available templates (Product Collection, Store Spotlight, Video), the auction response provides all necessary assets and content regardless of the template used, ensuring consistent integration across all campaign types.