Skip to main content
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
  • Product Highlight: Single product and a creative
  • Store Spotlight: Drives traffic directly to a vendor’s store page for brand awareness

​
Auction Request

Auction requests for Sponsored Brands follow the standard auction format with specific triggers for targeting and support for geolocation-based filtering:
{
  "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 identifier for location-based campaign filtering
  • opaqueUserId: Anonymous user identifier for personalization and enhanced targeting

​
Geolocation Filtering Behavior

The auction system automatically filters campaigns based on geolocation targeting:
  • Location Match: Campaigns with specific geolocation settings only participate when the geoTargeting field matches their configured locations
  • No Geolocation: Campaigns without geolocation restrictions participate in all auctions regardless of the geoTargeting value
  • Multiple Locations: Campaigns targeting multiple locations participate when the request matches any of their configured locations
  • Backward Compatibility: Existing campaigns without geolocation continue to work as before

​
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": "url",
          "id": "www.topsort.com",
          "vendorId": "vendor_id",
          "content": {
            "headline": "Campaign Headline",
            "logo": "https://some.url.com/logo.jpeg"
          },
          "campaignId": "018f3ff3-0d7c-7b75-bf99-629c62c09dc3",
          "productIds": ["pmk_1", "pmk_4", "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, Product Highlight, Store Spotlight), the auction response provides all necessary assets and content regardless of the template used, ensuring consistent integration across all campaign types.

​
Content Specifications

All creative assets (images and videos) uploaded for Sponsored Brands campaigns must meet these requirements:
  • Supported formats: JPEG, PNG, WEBP, GIF, MP4
  • Max file size: 5MB per creative/video
Last updated: