> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sponsored Brands Auction Request and Response

export const LastUpdated = ({date, lang = "en"}) => {
  const translations = {
    en: "Last updated:",
    es: "Última actualización:",
    pt: "Última atualização:",
    fr: "Dernière mise à jour:",
    de: "Zuletzt aktualisiert:"
  };
  const label = translations[lang] || translations.en;
  return <>
<style>{`
.last-updated-component {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 10px 16px;
border-radius: 8px;
margin-top: 12px;
margin-bottom: 16px;
font-size: 14px;
background-color: rgba(0, 0, 0, 0.05);
border: 1px solid rgba(0, 0, 0, 0.12);
color: rgba(0, 0, 0, 0.75);
line-height: 1;
}

        .last-updated-component svg {
          flex-shrink: 0;
          vertical-align: middle;
        }

        .last-updated-component span {
          display: inline-flex !important;
          align-items: center !important;
          line-height: 1 !important;
        }

        [data-theme="dark"] .last-updated-component {
          background-color: #3a3a3a;
          border: 2px solid #888888;
          color: #ffffff;
        }

        [data-theme="dark"] .last-updated-component svg {
          stroke: #ffffff;
        }
      `}</style>
      <div className="last-updated-component">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <circle cx="12" cy="12" r="10" />
          <polyline points="12 6 12 12 16 14" />
        </svg>
        <span>
          <strong style={{
    fontWeight: 600
  }}>{label}</strong> 
          <time dateTime={date}>{date}</time>
        </span>
      </div>
    </>;
};

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  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.
</div>

## Available Templates

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  Sponsored Brands campaigns are built using one of three pre-built templates:
</div>

* **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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  Auction requests for Sponsored Brands follow the standard auction format with
  specific triggers for targeting and support for geolocation-based filtering:
</div>

```json theme={null}
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "products": {
          "ids": ["pmk_1", "pmk_8"]
        },
        "category": {
          "id": "electronics"
        },
        "searchQuery": "cool electronics"
      },
      "geoTargeting": "santiago",
      "opaqueUserId": "user-123",
      "filter": {
        "operator": "or",
        "attributes": ["category:66e895c424dd8e36c1318b0c", "brand:nike"]
      }
    }
  ]
}
```

### 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
* **filter**: *(Optional)* Narrows the auction to ads whose attributes match the given `key:value` pairs — for example a specific category, brand, or color. Attributes are matched against values configured on each ad's entity (product, category, brand, etc.). Ads that don't match are excluded before ranking, so filtered-out bids never win or get charged. Requires additional integration and configuration; contact your Topsort representative to enable it.
  * **operator**: How to combine the attributes. Use `or` to keep ads matching **any** of the attributes (broader match), or `and` to keep only ads matching **all** of them (stricter match).
  * **attributes**: Up to 5 attributes in `key:value` format. The attribute name and value are limited to 40 characters each.

### Geolocation Filtering Behavior

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  The auction system automatically filters campaigns based on geolocation targeting:
</div>

* **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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  The auction response returns winning sponsored brands campaigns with complete
  creative assets and metadata:
</div>

```json theme={null}
{
  "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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  Creative assets for rendering the sponsored brands ad:
</div>

* **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

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  Campaign content for rendering:
</div>

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

## Implementation Notes

### Rendering Flexibility

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  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.
</div>

### Multi-Product Support

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  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.
</div>

### Template Integration

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  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.
</div>

### Content Specifications

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  All creative assets (images and videos) uploaded for Sponsored Brands
  campaigns must meet these requirements:
</div>

* **Supported formats**: JPEG, PNG, WEBP, GIF, MP4
* **Max file size**: 5MB per creative/video

***

<LastUpdated date="2025-11-18" />