Buying Workflow

A typical buy moves through five phases.

1. Discovery

Use adcp_get_products to find showcase inventory. Three buying modes:

• wholesale — return the full active product feed.
• brief — describe the campaign in natural language (for example, "CTV sports inventory under $20 CPM on Roku"); the server extracts structured filters and returns matching products.
• refine — iterate on a prior result with typed changes: include, omit, or more_like_this on specific products, or redirect the overall selection.

Lead with a brief for prose requirements, then refine to narrow the set.

2. Plan and execute

Use adcp_create_media_buy to turn the selected products into a buy. The whole buy becomes one campaign, and each package references one product and becomes one demand tag on that campaign.

Provide:

• The brand domain being promoted.
• Flight dates (start_time / end_time).
• A budget per package.
• A fresh idempotency_key (resending the same key returns the existing buy with replayed: true).

The campaign distributes immediately and lands in pending_creatives; creatives are attached later through the normal campaign flow. The response returns the media_buy_id (campaign id) and package_ids (demand tag ids).

3. Monitor

Use adcp_get_media_buys to list and inspect your buys — without needing to remember specific ids. It returns the operational state of each buy:

• Status, total budget, and the packages on the buy.
• Per-package creative-approval state.
• An optional near-real-time delivery snapshot per package (impressions, spend, pacing, delivery status) when you pass include_snapshot: true — ClearLine brands only.

Pass specific media_buy_ids to fetch particular buys, or filter the full list with status_filter (defaults to active); page through large result sets with pagination. Reach for this when you want a quick state check or light delivery glance; use adcp_get_media_buy_delivery for full reporting.

Each buy reports the valid_actions available in its current state — what adcp_update_media_buy will accept next.

4. Manage

Use adcp_update_media_buy to change a buy in flight (ClearLine brands). It applies PATCH semantics — only the fields you send change, and arrays replace the prior value. At the buy level you can pause/resume, cancel (irreversible), or shift start_time/end_time. Per package (by package_id) you can pause/cancel, adjust budget, change flight dates, or set a targeting_overlay.

• Cancellation deactivates the buy's packages so they stop serving; the record is retained so monitoring and reporting still work.
• The response returns the new media_buy_status, the affected_packages, and the available_actions for the new state.
• Appending packages (new_packages) is not yet supported — create a new media buy instead. Keyword/device/dayparting targeting has no equivalent and is reported back under unsupported_fields.

5. Reporting

On ClearLine brands, use adcp_get_media_buy_delivery with the media_buy_ids from your buy to retrieve:

• Per-buy totals: impressions, spend, clicks, CTR, completion rate, reach, and pacing index.
• A by_package breakdown (one entry per demand tag).
• Optional breakdowns by placement, geo, device type, and audience.
• Optional time-series windows (hourly or daily).

Campaigns not yet distributed report zero delivery.