Skip to main content

Programmatic Demand

This guide explains how programmatic line items (automated ad buying through external bidding systems) integrate with the ad server and compete with direct campaigns. It also shows an example configuration and how to test with the optional Prebid Server.

Overview​

Programmatic line items fetch bids from an external endpoint (such as a header bidding partner or ad exchange). During ad selection the server queries these endpoints in parallel, then ranks the returned prices against direct line items using normalized eCPM (effective cost per thousand impressions, a common metric for comparing different pricing models). This allows external demand to compete fairly with deals you sell directly.

Line Item Fields​

A programmatic line item uses the standard line item structure with two key fields:

Type     string // set to "programmatic"
Endpoint string // URL to request an OpenRTB bid

Other attributes such as targeting, pacing and budget work the same as direct deals. Here is a JSON example:

{
  "id": 42,  // Example line item ID
  "campaign_id": 10,  // Example campaign ID
  "publisher_id": 7,  // Example publisher ID
  "name": "Header Bidder",
  "type": "programmatic",
  "endpoint": "http://prebid-server:8000/openrtb2/auction",
  "budget_type": "cpm",
  "cpm": 0,  // Set to 0 - actual CPM comes from bid response
  "priority": "medium"
}

Bidding Flow​

  1. The server filters line items by targeting, pacing and caps.
  2. For each programmatic item it calls the Endpoint using the OpenRTB request.
  3. Returned bids are merged with direct line items and ranked by priority then price.
  4. The highest ranked creative is served and tracking URLs are generated.

Setting Up With Direct Demand​

Run docker compose --profile prebid up to start the optional Prebid Server (open-source header bidding solution) at http://localhost:8060. Create a line item like the JSON above and it will compete with any direct line items targeting the same request. Bids that clear your floors (minimum acceptable bid prices) simply override the ECPM of the programmatic line item when ranking.

During development you can also point the line item to http://localhost:8787/test/bid which always returns a fixed bid for testing.

What is Header Bidding? Header bidding is a programmatic advertising technique where multiple ad exchanges bid on inventory simultaneously before the ad server makes its final decision, maximizing publisher revenue by creating real-time competition for ad space.

What is Prebid? Prebid is the industry-standard open-source header bidding solution that manages connections to multiple demand partners and conducts unified auctions, simplifying programmatic integration for publishers.