> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# v3 readiness checklist
> The 8 minimum requirements for seller agents to pass AdCP v3 storyboard testing.
# v3 readiness checklist
AdCP storyboard testing requires v3 protocol support. Agents that only support v2 will fail. This page covers the minimum changes to unblock integration testing with v3 buyers — not the full migration. For the complete list, see the [migration guide](/docs/reference/migration).
Storyboard testing will hard-fail any agent that does not declare v3 support. Complete these 8 items first, then work through the [full migration checklist](/docs/reference/migration). v2 is fully deprecated on August 1, 2026 (UTC) — see the [v2 sunset page](/docs/reference/v2-sunset).
***
## 1. Implement `get_adcp_capabilities`
v3 buyers call this task first to discover what your agent supports. Without it, buyers cannot determine your protocol version, supported channels, pricing models, or features.
This is the single most important change — it's how buyers (and storyboard testing) distinguish v3 agents from v2.
Return at minimum: `major_versions: [3]`, `supported_protocols`, and your `features` object.
Task specification and response schema.
***
## 2. Update channel taxonomy
v3 replaces v2's 9 channels with 20 planning-oriented channels. Buyers send v3 channel values — your agent must recognize them.
| Common v2 value | v3 replacement |
| --------------- | --------------------------------------------------- |
| `video` | `olv`, `linear_tv`, or `cinema` |
| `audio` | `radio` or `streaming_audio` |
| `native` | Removed — native inventory is now part of `display` |
| `retail` | `retail_media` |
`display`, `social`, `ctv`, `podcast`, and `dooh` are unchanged.
Complete mapping table and examples.
***
## 3. Rename pricing fields
Two field renames — same semantics, different names:
| v2 field | v3 field |
| ---------------------- | ------------------------- |
| `fixed_rate` | `fixed_price` |
| `price_guidance.floor` | `floor_price` (top-level) |
Buyers validate against v3 schemas. The old field names cause schema validation failures.
Before/after examples and price guidance restructuring.
***
## 4. Support `creative_assignments`
`creative_ids` (string array) is replaced by `creative_assignments` (object array) with delivery weighting and placement targeting.
```json theme={null}
// v2
{ "creative_ids": ["cr_001", "cr_002"] }
// v3
{ "creative_assignments": [
{ "creative_id": "cr_001", "weight": 70 },
{ "creative_id": "cr_002", "weight": 30 }
]
}
```
Weighted assignments, placement targeting, and asset discovery.
***
## 5. Accept `brand` ref instead of `brand_manifest`
Buyers pass brand identity as a reference (`{ domain, brand_id }`) instead of an inline manifest. Your agent resolves brand data from `brand.json` or the registry at execution time.
```json theme={null}
// v2
{ "brand_manifest": { "name": "Acme", "logo": "..." } }
// v3
{ "brand": { "domain": "acme.example.com", "brand_id": "acme_main" } }
```
BrandRef schema, resolution flow, and migration steps.
***
## 6. Handle `buying_mode` on `get_products`
`buying_mode` is now required on every `get_products` request. `brief` is the baseline mode for curated product discovery. If your agent declares `wholesale` or `refine` in `media_buy.buying_modes`, it must handle those mode semantics as well.
Full request schema including buying\_mode.
***
## 7. Remove `buyer_ref` — use `idempotency_key`
v3 removes `buyer_ref`, `buyer_campaign_ref`, and `campaign_ref` from all requests and responses. Seller-assigned `media_buy_id` and `package_id` are now the only canonical identifiers.
If your agent relied on `buyer_ref` for deduplication, use the new `idempotency_key` field instead. `idempotency_key` (UUID v4) is **required** on every mutating request — agents MUST reject requests that omit it with `INVALID_REQUEST`, and MUST return `IDEMPOTENCY_CONFLICT` when a key is reused with a different payload. See the [idempotency implementation guide](/docs/building/implementation/security#idempotency) for normative semantics.
If your agent used `buyer_ref` for internal tracking or correlation (e.g. mapping to campaign IDs, session traces, or UI state), use the `context` field instead. `context` is an opaque object echoed unchanged in every response and webhook — agents must never parse or act on it. For `create_media_buy` package correlation, put per-package tracking in `packages[i].context` (for example `context.buyer_ref`), not deprecated top-level `buyer_ref`; 3.1+ sellers MUST echo `product_id` on explicit package responses, and package context remains the fallback for legacy sellers that do not.
| v2 field | v3 replacement |
| ------------------------------------- | ----------------------------------------------- |
| `buyer_ref` | Removed — use `media_buy_id` (seller-assigned) |
| `buyer_campaign_ref` | Removed |
| `campaign_ref` | Removed |
| `buyer_ref` as implicit dedup | Explicit `idempotency_key` on mutating requests |
| `buyer_ref` as correlation / tracking | `context` (opaque, echoed unchanged) |
```json theme={null}
// v2 — buyer provides their own ref
{ "buyer_ref": "camp-2024-q3", "start_time": "..." }
// v3 — seller-assigned ID, explicit idempotency, context for tracking
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"context": { "campaign": "camp-2024-q3", "trace_id": "abc-123" },
"start_time": "..."
}
```
For package-level line-item correlation, keep the buy-level context separate from each package's fallback correlation handle:
```json test=false theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440001",
"context": {
"internal_campaign_id": "camp-2024-q3"
},
"brand": {
"domain": "example-brand.test"
},
"packages": [
{
"product_id": "prod_weekday_display",
"pricing_option_id": "cpm_usd_auction",
"format_ids": [
{
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_image"
}
],
"budget": 12000,
"context": {
"buyer_ref": "line-001"
}
},
{
"product_id": "prod_weekend_video",
"pricing_option_id": "cpm_usd_auction",
"format_ids": [
{
"agent_url": "https://creative.adcontextprotocol.org",
"id": "video_standard_30s"
}
],
"budget": 18000,
"context": {
"buyer_ref": "line-002"
}
}
],
"start_time": "2026-07-01T00:00:00Z",
"end_time": "2026-07-31T23:59:59Z"
}
```
***
## 8. Implement `sync_accounts`
v3 buyers establish billing relationships before placing buys. Your agent must accept `sync_accounts` calls and return an account reference that buyers include on subsequent requests.
Account provisioning, lifecycle, and the sync\_accounts task.
***
## After these 8 items
Once these are in place, run storyboard testing against your agent. The existing tracks (products, media buy, creative) validate v3 schemas in detail and will surface any remaining field-level issues.
For the complete migration — including geo targeting, optimization goals, signals, audiences, and attribution — see the [full migration guide](/docs/reference/migration).