Better integration with current systems

Campaign Change Webhook

The campaign change webhook allows us to notify users about updates in Topsort’s system, eliminating the need for constant polling. This reduces the API load by informing users with a single request when changes occur.

Key benefits

• Synchronization: Ensures the marketplace has up-to-date information aligned with Topsort’s platform, preventing unsynchronized data issues.

How it works

This webhook triggers whenever key changes happen to campaigns in Topsort, such as:

• campaign:create
• campaign:update
• campaign:delete
• bid:create
• bid:update
• bid:delete

Each event triggers a POST JSON request to subscribed webhooks with the following a specific payload.

Campaign ID in Auction Response

Incorporating campaign IDs in auction responses allows clients to map Topsort auctions to their internal campaigns.

Key Benefits:

• Tracking: Clients can store auction data to perform analysis and optimizations.
• Integration: Link Topsort campaign performance to external platforms like GA4.

How It Works:

Each winning product or banner in an auction response now includes a campaign_id.

Example:

{
  "results": [{
    "resultType": "listings",
    "winners": [
      {
        "rank": 1,
        "type": "product",
        "id": "771860",
        "resolvedBidId": "ChAGa8u1DSh2ZYkEcUqZAQPhEhABkS1FACZ4ko2uUXufbQ6WGhAGQ57M6WZx7pskxnrwxTQeIgoKBjc3MTg2MBABMOTrAQ",
        "campaign_id": "01903525-2b99-72a8-a610-380b6910885c"
      }
    ],
    "error": false
  }]
}

Product Metadata in the Catalog

Product metadata allows clients to attach custom information to products in their catalog, facilitating better organization and searchability.

Key Benefits:

• Facilitated Integration: Custom fields help retailers track products and their upload time.
• Enhanced Advertiser Experience: Advertisers can easily identify which products are being promoted with additional metadata.

How It Works:

Clients can add metadata through a JSON object during product upserts. The JSON follows these constraints:

• Must be one level deep (no sub-objects).
• Allows string, integer, and float as value types.
• Supports up to 8 key-value pairs.
• Key max length: 16 characters.
• Value max length: 32 characters.

Example:

{
  "products": [{
    "id": "24-MB02",
    "name": "Crown Summit Backpack",
    "metadata": {
      "size": "L",
      "color": "blue"
    }
  }]
}