Media Buy Lifecycle

Media buys represent the complete lifecycle of advertising campaigns in AdCP. The AdCP:Buy protocol provides a unified interface for managing media buys across multiple advertising platforms, from initial campaign creation through ongoing optimization and updates.

Overview

AdCP’s media buy management provides a unified interface for:

Campaign Creation from discovered products and packages
Lifecycle Management through all campaign states
Budget and Targeting Updates for ongoing optimization
Cross-Platform Orchestration with consistent operations
Asynchronous Operations with human-in-the-loop support

The Media Buy Lifecycle Phases

1. Creation Phase

Transform discovered products into active advertising campaigns using create_media_buy:

Package Configuration: Combine products with formats, targeting, and budget
Campaign Setup: Define timing, overall budget, and promoted offering
Validation & Approval: Automated checks with optional human approval
Platform Deployment: Campaign creation across advertising platforms

This phase may involve:

Immediate creation with pending_activation status
Human approval workflow with pending_manual status
Permission requirements with pending_permission status

Platform Mapping:

Google Ad Manager: Creates an Order with LineItems
Kevel: Creates a Campaign with Flights
Triton Digital: Creates a Campaign with Flights

2. Creative Upload Phase

Once created, the media buy requires creative assets via sync_creatives:

Platform-specific format support (video, audio, display, custom)
Validation and policy review for creative compliance
Assignment to specific packages for targeted delivery

3. Activation & Delivery Phase

Monitor and manage active campaigns:

Status Tracking: Campaign transitions from pending_activation to active
Creative Assignment: Attach assets from the creative library
Delivery Monitoring: Track pacing and performance metrics with get_media_buy_delivery
Issue Resolution: Handle approval delays and platform issues

4. Optimization & Reporting Phase

Ongoing performance monitoring and data-driven campaign optimization using AdCP’s comprehensive reporting tools. Key activities include:

Performance monitoring with real-time and historical analytics
Campaign optimization through budget reallocation and targeting refinement
Dimensional reporting using the same targeting dimensions for consistent analysis
AI-driven insights through performance feedback loops

For complete details on optimization strategies, performance monitoring, standard metrics, and best practices, see Optimization & Reporting.

Key Concepts

Media Buy Structure

A media buy contains:

Campaign metadata (buyer reference, promoted offering, timing)
Overall budget with currency and pacing preferences
Multiple packages representing different targeting/creative combinations
Status tracking through creation, approval, and execution phases

Package Model

Packages are the building blocks of media buys:

Single product selection from discovery results - when you buy a product, you buy the entire product
Creative formats to be provided for this package
Targeting overlays for audience refinement beyond product defaults
Budget allocation as portion of overall media buy budget
Pricing option selection from product’s available pricing models
Pacing strategy for budget delivery (even, asap, or front_loaded)
Bid price for auction-based pricing models (when applicable)

Creative Assignment and Placement Targeting

When a product defines multiple placements, buyers can assign different creatives to different placements while still purchasing the entire product. Key Points:

Packages buy the entire product - you cannot target individual placements at the package level
Placement targeting happens only at the creative assignment level
Creatives without placement_ids run on all placements in the product

Example Workflow:

Product defines placements:

{
  "product_id": "news_site_premium",
  "placements": [
    {
      "placement_id": "homepage_banner",
      "name": "Homepage Banner",
      "format_ids": [{"agent_url": "...", "id": "display_728x90"}]
    },
    {
      "placement_id": "article_sidebar",
      "name": "Article Sidebar",
      "format_ids": [{"agent_url": "...", "id": "display_300x250"}]
    }
  ]
}

Buyer creates package (buys entire product) and assigns different creatives to each placement:

{
  "product_id": "news_site_premium",
  "creative_assignments": [
    {
      "creative_id": "creative_homepage",
      "placement_ids": ["homepage_banner"]
    },
    {
      "creative_id": "creative_article",
      "placement_ids": ["article_sidebar"]
    }
  ]
}

Or assign one creative to all placements (omit placement_ids):

{
  "product_id": "news_site_premium",
  "creative_assignments": [
    {
      "creative_id": "creative_universal"
      // No placement_ids = runs on all placements in the product
    }
  ]
}

Use Cases:

Format-specific placements: Homepage takes 728x90, sidebar takes 300x250
A/B testing: Test different creatives on different placements
Geo-targeting: Different creatives for different DOOH screen locations
Dayparting: Different creatives for morning vs evening placements

See Media Products - Placements for complete placement documentation.

Lifecycle States

Media buys progress through predictable states:

pending_activation: Created, awaiting platform setup
pending_manual: Requires human approval
active: Running and delivering impressions
paused: Temporarily stopped
completed: Finished successfully

Core Operations

Creating Media Buys

The creation process handles:

Product validation ensuring discovered products are still available
Format compatibility checking creative requirements across packages
Budget distribution allocating spend across multiple packages
Platform coordination creating campaigns across multiple ad servers

Updating Media Buys

Modification capabilities include:

Budget adjustments for increased/decreased spend
Targeting updates to refine audience parameters
Package modifications adding/removing products and formats
Schedule changes for extended or shortened campaign timing

Status Management

Campaign state transitions:

Activation requests to start pending campaigns
Pause/resume operations for campaign control
Completion handling for successful campaign closure
Error recovery for failed operations

Response Times

Media buy operations use a unified status system with predictable timing:

create_media_buy: Instant to days
- completed: Simple campaigns created immediately
- working: Processing within 120 seconds (validation, setup)
- submitted: Complex campaigns requiring hours to days (human approval)
update_media_buy: Instant to days
- completed: Budget changes applied immediately
- working: Targeting updates within 120 seconds
- submitted: Package modifications requiring approval (hours to days)
get_media_buy_delivery: ~60 seconds (data aggregation)
Performance analysis: ~1 second (cached metrics)

Status Meanings:

completed: Operation finished, process results immediately
working: Processing, expect completion within 120 seconds
submitted: Long-running operation, provide webhook or poll with tasks/get

Best Practices

Campaign Planning

Start with clear objectives defined in your product discovery brief
Plan package structure around distinct audience/creative combinations
Set realistic budgets based on product pricing guidance
Allow time for approval in publisher workflows

Ongoing Management

Monitor daily pacing to ensure delivery against targets
Review performance weekly for optimization opportunities
Update targeting gradually to avoid disrupting delivery
Refresh creatives regularly to prevent audience fatigue

Budget Management

Allocate conservatively initially, then increase based on performance
Reserve budget for high-performing packages
Plan for seasonality in audience availability and pricing
Monitor spend efficiency across different targeting approaches
Budget Management: The system automatically recalculates impressions based on CPM when budgets are updated

Technical Implementation

Pause/Resume Strategy: Use campaign-level controls for maintenance, package-level for optimization
Performance Monitoring: Regular status checks and delivery reports ensure campaigns stay on track
Asynchronous Design: Design orchestrators to handle long-running operations gracefully
Task Tracking: Maintain persistent storage for pending task IDs
Webhook Integration: Implement webhooks for real-time updates
User Communication: Clearly communicate pending states to end users

Error Handling

For comprehensive error handling guidance including pending vs error states, response patterns, and recovery strategies, see Protocol Error Handling. Media buy specific error codes are documented in each task specification and the Error Codes Reference.

Asynchronous Operations and Human-in-the-Loop

The AdCP:Buy protocol is designed for asynchronous operations as a core principle. Orchestrators MUST handle pending states gracefully.

Human-in-the-Loop (HITL) Operations

Many publishers require manual approval for automated operations. The protocol supports this through the HITL task queue:

Operation Request: Orchestrator calls any modification task
Pending Response: Server returns pending_manual status with task ID
Task Monitoring: Orchestrator polls or receives webhooks
Human Review: Publisher reviews and approves/rejects
Completion: Original operation executes upon approval

HITL Task States

pending → assigned → in_progress → completed/failed
                  ↓
              escalated

Orchestrator Requirements

Orchestrators MUST:

Handle pending_manual and pending_permission as normal states
Store task IDs for tracking pending operations
Implement retry logic with exponential backoff
Handle eventual rejection of operations gracefully
Support webhook callbacks for real-time updates (recommended)

Standard Metrics

All platforms must support these core metrics:

impressions: Number of ad views
spend: Amount spent in currency
clicks: Number of clicks (if applicable)
ctr: Click-through rate (clicks/impressions)

Optional standard metrics:

conversions: Post-click/view conversions
viewability: Percentage of viewable impressions
completion_rate: Video/audio completion percentage
engagement_rate: Platform-specific engagement metric

Platform-Specific Considerations

Different platforms offer varying reporting and optimization capabilities:

Google Ad Manager

Orders can contain multiple LineItems
LineItems map 1:1 with packages
Sophisticated targeting and frequency capping
Requires creative approval process
Reporting: Comprehensive dimensional reporting, real-time and historical data, advanced viewability metrics

Kevel

Campaigns contain Flights
Flights map 1:1 with packages
Real-time decisioning engine
Supports custom creative templates
Reporting: Real-time reporting API, custom metric support, flexible aggregation options

Triton Digital

Optimized for audio advertising
Campaigns contain Flights for different dayparts
Strong station/stream targeting capabilities
Audio-only creative support
Reporting: Audio-specific metrics (completion rates, skip rates), station-level performance data, daypart analysis

Advanced Analytics

Cross-Campaign Analysis

Portfolio performance across multiple campaigns
Audience overlap and frequency management
Budget allocation optimization across campaigns

Predictive Insights

Performance forecasting based on historical data
Optimization recommendations from AI analysis
Trend prediction for proactive adjustments

Integration Patterns

Discovery to Media Buy

Seamless flow from product discovery to campaign creation:

Use get_products to find inventory
Select products that align with campaign objectives
Configure packages with appropriate targeting and formats
Create media buy with create_media_buy

Creative Integration

Coordinate with creative management:

Understand format requirements from selected products
Prepare assets using Creative Management
Assign creatives during campaign creation or via updates
Monitor creative performance and refresh as needed

Performance Optimization

Data-driven campaign improvement leveraging comprehensive analytics:

Track delivery with get_media_buy_delivery
- Monitor real-time delivery metrics and pacing analysis
- Get package-level performance breakdown for optimization opportunities
- Track performance across different targeting approaches
Analyze performance across packages and targeting
- Use dimensional reporting for granular insights
- Monitor performance index scores for AI-driven optimization
- Identify high and low performing segments
Update campaigns with update_media_buy
- Reallocate budgets between high and low performing packages
- Adjust targeting based on performance data
- Pause underperforming packages and scale successful ones
Iterate based on performance data and business outcomes
- Feed performance data back into optimization algorithms
- Continuously refine targeting and creative assignments
- Scale successful strategies across similar campaigns

Optimization Best Practices

Report Frequently: Regular reporting improves optimization opportunities
Track Pacing: Monitor delivery against targets to avoid under/over-delivery
Analyze Patterns: Look for performance trends across dimensions
Consider Latency: Some metrics may have attribution delays
Normalize Metrics: Use consistent baselines for performance comparison

Product Discovery - Finding inventory for media buys
Task Reference - Complete API documentation
Creatives - Creative asset management
Orchestrator Design Guide - Implementation best practices

Getting Started

Protocols

Signals Protocol

Curation Protocol

Media Buy Protocol

Creative

Reference

​Media Buy Lifecycle

​Overview

​The Media Buy Lifecycle Phases

​1. Creation Phase

​2. Creative Upload Phase

​3. Activation & Delivery Phase

​4. Optimization & Reporting Phase

​Key Concepts

​Media Buy Structure

​Package Model

​Creative Assignment and Placement Targeting

​Lifecycle States

​Core Operations

​Creating Media Buys

​Updating Media Buys

​Status Management

​Response Times

​Best Practices

​Campaign Planning

​Ongoing Management

​Budget Management

​Technical Implementation

​Error Handling

​Asynchronous Operations and Human-in-the-Loop

​Human-in-the-Loop (HITL) Operations

​HITL Task States

​Orchestrator Requirements

​Standard Metrics

​Platform-Specific Considerations

​Google Ad Manager

​Kevel

​Triton Digital

​Advanced Analytics

​Cross-Campaign Analysis

​Predictive Insights

​Integration Patterns

​Discovery to Media Buy

​Creative Integration

​Performance Optimization

​Optimization Best Practices

​Related Documentation