Buying workflow

Start with an authorized buyer account and get_adcp_capabilities. Then work through the steps below. Discovery is read-only; creation, creative sync, and updates can change real campaign objects.

1. Discover products

Use get_products in the mode that fits your task:

• brief — send the campaign requirements as natural language. The original text is ranked directly against buyer-accessible inventory, with no second model call inside search.
• wholesale — browse the active buyer-scoped feed, newest first.
• refine — rerank current inventory with typed changes: include or omit a product, find similar products, or redirect the request. Proposal-level refinement is not supported.

Use pagination.max_results (1–100, default 50) and the returned pagination.cursor to continue through results. For hard requirements, send filters.delivery_type or source and transaction-rate constraints in filters.ext.magnite. Brief text alone does not enforce these as hard filters.

A product result is a discovery result, not a reservation or a delivery guarantee. Keep the selected product IDs and pricing models for the next step.

2. Create the buy

Use create_media_buy with:

• Advertiser identity: brand.domain (for example, nike.com), or an existing demand_partner_id or exact demand_partner_name.
• Flight: start_time ("asap" or an ISO date-time) and end_time (a later ISO date-time).
• Packages: one per selected product, each with product_id, a positive budget in the account currency, and pricing_option_id using the product's pricing model. A product can appear only once; the maximum is 25 packages.
• Retry key: a fresh idempotency_key for each new intended buy. Reuse it only for a retry of that same buy.

The successful response returns a media_buy_id (ClearLine campaign ID) and package IDs (ClearLine demand tag IDs). Save these for subsequent calls.

Provisioned is not the same as serving. Automated purchase paths provision immediately, but new objects generally inherit account activation defaults. A buy can still be paused, awaiting creatives, or waiting for its flight to start.

Direct IO, sourced Streaming Marketplace, and sourced DV+ Marketplace products use automated provisioning. Only a DV+ Publisher/PMP deal without an automated source uses the manual path: the result identifies it with DISTRIBUTION_FAILED, retains the created campaign, and provides setup steps. Do not predict manual setup from the product name.

A failed creation can leave a campaign or packages already provisioned. Read any recovery IDs and instructions before retrying; a new key could create a second buy. An existing successful buy may be replayed with replayed: true, but changed payloads are not checked for idempotency conflicts.

3. Prepare creatives

Supply optional inline creatives during creation and reference their IDs from each package, or use sync_creatives after the buy exists. Inline creative failures are best-effort: the buy can be created even if a creative fails, so inspect the creative results.

• Use VAST tag URLs or hosted video URLs. Inline VAST XML and tile assets are not supported.
• Call list_creatives to inspect existing assets and assignments. creative_id is the creative name; platform_creative_id is its numeric ClearLine ID.
• sync_creatives upserts by creative_id and assigns creatives to package IDs. Provide a landing-page URL or advertiser domain; sync has no brand-level fallback.
• Unmentioned assignments are preserved by default. With delete_missing: true, assignments become authoritative for touched packages and omitted creatives can be deactivated. Use this deliberately.
• dry_run: true validates and resolves inputs without making ClearLine calls. It does not validate live publisher approval.

Check creative approval and activation before expecting delivery.

4. Check readiness

Use get_media_buys to inspect status, packages, budgets, and per-package creative approval. Pass media_buy_ids to retrieve specific buys regardless of status.

Without IDs, listing defaults to status_filter: ["active"]. If a new buy appears to be missing, request its ID or include the relevant states, such as paused, pending_creatives, and pending_start. Results cover campaigns in the selected account, including ones created outside Orchestration.

Use pagination for larger lists. On ClearLine brands, include_snapshot: true adds a lightweight delivery snapshot. For full reporting, use the delivery tool in step 6.

Read each buy's valid_actions before requesting the next change. Status alone does not confirm that every creative or publisher-side object is active.

5. Manage the buy

On ClearLine brands, use update_media_buy with media_buy_id. Send only the fields you intend to change.

Cancellation is buy-level only and irreversible. There is no per-package cancellation. The canceled record remains available for monitoring and reporting.

Structured geo targeting supports state regions and postal areas. Keyword, device, audience, dayparting, and other unsupported targeting inputs are returned in unsupported_fields; accepting a field is not the same as applying it.

Adding or replacing packages

new_packages is supported. New Direct IO tags start inactive; other new tag types use account activation defaults. Attachment does not copy or allocate budgets and creatives. Set the budget, assign creatives, then resume when ready. Reused tags retain their existing budget and activation.

Attachments run sequentially and are non-idempotent. A partial failure can leave completed attachments or other provisioned objects. Inspect recovery IDs and re-fetch the buy before deciding what to retry.

What pause and resume actually change

Pause/resume changes the buyer's ClearLine campaign and affected demand tags. Shared ClearLine supply deals retain their state; publisher-owned SpringServe objects are not toggled.

Creative activation changes only when all assignments are within the affected tags and request the same state. Shared creatives or uncertain assignments retain their state, with CREATIVE_ACTIVATION_PRESERVED warnings where applicable. An inactive shared creative can therefore remain inactive after a resume and need explicit activation before serving.

Inspect the returned status, affected packages, available actions, and warnings. If an update partially fails, some changes may already have been applied: fetch the buy before retrying.

6. Read delivery

On ClearLine brands, use get_media_buy_delivery with media_buy_ids 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).

For time series, set include_window_breakdown: true and time_granularity to hourly or daily. Reporting defaults to active buys; set status_filter explicitly when inspecting paused, completed, or canceled buys.

Omitted dates use a trailing 30-day window. start_date is inclusive and end_date is exclusive. Future end dates are capped at the current UTC date, and a wholly future range returns zero delivery. Campaigns not yet distributed also report zero delivery.

Zero delivery is a result to investigate, not proof of failure. Check the report window, status filter, flight dates, activation, and creative approval before changing the buy.