{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/3.1.0-rc.4/media-buy/get-media-buy-delivery-response.json", "title": "Get Media Buy Delivery Response", "description": "Response payload for get_media_buy_delivery task", "type": "object", "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/version-envelope.json" }, { "$ref": "/schemas/3.1.0-rc.4/core/protocol-envelope.json" } ], "properties": { "notification_type": { "type": "string", "enum": [ "scheduled", "final", "delayed", "adjusted", "window_update" ], "description": "Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with corrected data (same window), window_update = resending period with a wider measurement window (e.g., C3 superseding live, C7 superseding C3)" }, "partial_data": { "type": "boolean", "description": "Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)" }, "unavailable_count": { "type": "integer", "minimum": 0, "description": "Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)" }, "sequence_number": { "type": "integer", "minimum": 1, "description": "Sequential notification number (only present in webhook deliveries, starts at 1)" }, "next_expected_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')" }, "reporting_period": { "type": "object", "description": "Date range for the report. All periods use UTC timezone.", "properties": { "start": { "type": "string", "format": "date-time", "description": "ISO 8601 start timestamp in UTC (e.g., 2024-02-05T00:00:00Z)" }, "end": { "type": "string", "format": "date-time", "description": "ISO 8601 end timestamp in UTC (e.g., 2024-02-05T23:59:59Z)" } }, "required": [ "start", "end" ], "additionalProperties": true }, "currency": { "type": "string", "description": "ISO 4217 currency code", "pattern": "^[A-Z]{3}$" }, "attribution_window": { "$ref": "/schemas/3.1.0-rc.4/core/attribution-window.json", "description": "Attribution methodology and lookback windows used for conversion metrics in this response. All media buys from a single seller share the same attribution methodology. Enables cross-platform comparison (e.g., Amazon 14-day click vs. Criteo 30-day click)." }, "aggregated_totals": { "type": "object", "description": "Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.", "properties": { "impressions": { "type": "number", "description": "Total impressions delivered across all media buys", "minimum": 0 }, "spend": { "type": "number", "description": "Total amount spent across all media buys", "minimum": 0 }, "clicks": { "type": "number", "description": "Total clicks across all media buys (if applicable)", "minimum": 0 }, "completed_views": { "type": "number", "description": "Total audio/video completions across all media buys (if applicable)", "minimum": 0 }, "views": { "type": "number", "description": "Total views across all media buys (if applicable)", "minimum": 0 }, "conversions": { "type": "number", "description": "Total conversions across all media buys (if applicable)", "minimum": 0 }, "conversion_value": { "type": "number", "description": "Total conversion value across all media buys (if applicable)", "minimum": 0 }, "roas": { "type": "number", "description": "Aggregate return on ad spend across all media buys (total conversion_value / total spend)", "minimum": 0 }, "new_to_brand_rate": { "type": "number", "description": "Fraction of total conversions across all media buys from first-time brand buyers (weighted by conversion volume, not a simple average of per-buy rates)", "minimum": 0, "maximum": 1 }, "cost_per_acquisition": { "type": "number", "description": "Aggregate cost per conversion across all media buys (total spend / total conversions)", "minimum": 0 }, "completion_rate": { "type": "number", "description": "Aggregate completion rate across all media buys (weighted by impressions, not a simple average of per-buy rates)", "minimum": 0, "maximum": 1 }, "reach": { "type": "number", "description": "Deduplicated reach across all media buys (if the seller can deduplicate across buys; otherwise sum of per-buy reach). Only present when all media buys share the same reach_unit. Omitted when reach units are heterogeneous — use per-buy reach values instead.", "minimum": 0 }, "reach_unit": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/enums/reach-unit.json" } ], "description": "Unit of measurement for reach. Only present when all aggregated media buys use the same reach_unit." }, "frequency": { "type": "number", "description": "Average frequency per reach unit across all media buys (impressions / reach when cross-buy deduplication is available). Only present when reach is present.", "minimum": 0 }, "media_buy_count": { "type": "integer", "description": "Number of media buys included in the response", "minimum": 0 }, "metric_aggregates": { "type": "array", "description": "Cross-buy delivery aggregates partitioned by qualifier. Row-symmetric with `package.committed_metrics` and `by_package[].missing_metrics` — same atomic unit `(scope, metric_id, qualifier)` — so reconciliation collapses to a row-level join on the tuple. Granularity rule: one row per `(metric_id, full-qualifier-set)`, reported at the finest available granularity; buyers re-aggregate up if they want a coarser view. Used only for metrics with non-empty qualifier sets — unqualified metrics (`impressions`, `spend`, `media_buy_count`, etc.) remain at the top of `aggregated_totals`. **Mutual exclusion MUST**: for any `metric_id` appearing in `metric_aggregates`, the corresponding top-level scalar in `aggregated_totals` MUST be omitted (not zeroed) — avoids duplicate sources of truth. The qualifier vocabulary on this delivery surface is closed today (`additionalProperties: false`, same content as `committed_metrics.qualifier`) but is expected to **diverge from contract qualifier in future minors** as transparency disclosures buyers don't commit to ship delivery-only (e.g., `tracker_firing` pending #3832 resolution). Each row carries a `value` plus inlined per-metric component fields (e.g., `measurable_impressions` and `viewable_impressions` for `viewable_rate`; `spend` and `conversions` for `cost_per_acquisition`). Per-buy `totals` keeps its flat shape — each buy is single-qualifier by definition; only the aggregate spans qualifiers. **Qualifier-set drift across reports**: when a campaign gains a new qualifier mid-flight (e.g., adds `tracker_firing` partitioning in week 2), prior periods' rows remain valid at their original granularity; buyers SHOULD NOT retroactively repartition.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metric-aggregate.json" }, "examples": [ [ { "scope": "standard", "metric_id": "viewable_rate", "qualifier": { "viewability_standard": "mrc" }, "value": 0.7286, "measurable_impressions": 700000, "viewable_impressions": 510000 }, { "scope": "standard", "metric_id": "viewable_rate", "qualifier": { "viewability_standard": "groupm" }, "value": 0.55, "measurable_impressions": 180000, "viewable_impressions": 99000 }, { "scope": "vendor", "vendor": { "domain": "attentionvendor.example" }, "metric_id": "attention_units", "qualifier": {}, "value": 4.2, "measurable_impressions": 800000 } ] ] } }, "required": [ "impressions", "spend", "media_buy_count" ], "additionalProperties": true }, "media_buy_deliveries": { "type": "array", "description": "Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.", "items": { "type": "object", "properties": { "media_buy_id": { "type": "string", "description": "Seller's media buy identifier", "x-entity": "media_buy" }, "status": { "type": "string", "description": "Current media buy status. Lifecycle states use the same taxonomy as media-buy-status (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled`). In webhook context, reporting_delayed indicates data temporarily unavailable. `pending` is accepted as a legacy alias for pending_start.", "enum": [ "pending_creatives", "pending_start", "pending", "active", "paused", "completed", "rejected", "canceled", "failed", "reporting_delayed" ] }, "expected_availability": { "type": "string", "format": "date-time", "description": "When delayed data is expected to be available (only present when status is reporting_delayed)" }, "is_adjusted": { "type": "boolean", "description": "Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals." }, "is_final": { "type": "boolean", "description": "Whether this row's delivery data is final for the reporting period. The row does not carry its own `measurement_window` — that lives on each `by_package[*]` entry. Reconciliation joins on per-package `measurement_window`; this row-level flag is a convenience roll-up. Sellers MUST NOT emit `is_final: true` at the row level unless every entry in `by_package` has `is_final: true` for the same `measurement_window` as the buy's `measurement_terms.billing_measurement.measurement_window` (or for the row's natural window when no `billing_measurement.measurement_window` is set). On any disagreement between row-level and package-level finality, package-level is authoritative. When true, the seller considers these numbers closed and is willing to invoice on them subject to `measurement_terms.billing_measurement`. When false, numbers may still move as measurement matures (broadcast C3 → C7) or processing completes (IVT scrubbing, dedup). When absent, the seller does not distinguish provisional from final at the row level — consult per-package `is_final`." }, "finalized_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which this row became final. Present only when `is_final: true`. Anchors the buyer's reconciliation and (when later defined) dispute-window clocks against the buy's `measurement_terms.billing_measurement`. Computed as the latest `finalized_at` across the row's packages for the reconciliation window." }, "pricing_model": { "$ref": "/schemas/3.1.0-rc.4/enums/pricing-model.json", "description": "Pricing model used for this media buy" }, "totals": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "description": "Aggregate metrics for this media buy across all packages", "properties": { "effective_rate": { "type": "number", "description": "Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')", "minimum": 0 } }, "required": [ "spend" ] } ] }, "by_package": { "type": "array", "description": "Metrics broken down by package", "items": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "properties": { "package_id": { "type": "string", "description": "Seller's package identifier", "x-entity": "package" }, "pacing_index": { "type": "number", "description": "Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)", "minimum": 0 }, "pricing_model": { "$ref": "/schemas/3.1.0-rc.4/enums/pricing-model.json", "description": "The pricing model used for this package (e.g., cpm, cpcv, cpp). Indicates how the package is billed and which metrics are most relevant for optimization." }, "rate": { "type": "number", "description": "The pricing rate for this package in the specified currency. For fixed-rate pricing, this is the agreed rate (e.g., CPM rate of 12.50 means $12.50 per 1,000 impressions). For auction-based pricing, this represents the effective rate based on actual delivery.", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR, GBP) for this package's pricing. Indicates the currency in which the rate and spend values are denominated. Different packages can use different currencies when supported by the publisher.", "pattern": "^[A-Z]{3}$" }, "delivery_status": { "type": "string", "description": "System-reported operational state of this package. Reflects actual delivery state independent of buyer pause control.", "enum": [ "delivering", "completed", "budget_exhausted", "flight_ended", "goal_met" ] }, "paused": { "type": "boolean", "description": "Whether this package is currently paused by the buyer" }, "is_final": { "type": "boolean", "description": "Whether this delivery data is final for the reporting period. When false, the data may be updated as measurement matures (e.g., broadcast C7 window accumulating DVR playback) or as processing completes (e.g., IVT filtering, deduplication). When true, the seller considers this data closed — no further updates for this period — and is willing to invoice on it subject to the buy's `measurement_terms.billing_measurement`. Absent means the seller does not distinguish provisional from final data." }, "finalized_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which this package's data became final. Present only when `is_final: true`. Anchors reconciliation and (when later defined) dispute-window clocks against the buy's `measurement_terms.billing_measurement.measurement_window`." }, "measurement_window": { "type": "string", "maxLength": 50, "description": "Which measurement window this data represents, referencing a window_id from the product's reporting_capabilities.measurement_windows. For broadcast: 'live', 'c3', 'c7'. When absent, the data is not windowed (standard digital reporting). When present with is_final: false, a later report for the same period will provide a wider window or more complete data.", "examples": [ "live", "c3", "c7" ] }, "supersedes_window": { "type": "string", "maxLength": 50, "description": "Which measurement window this data replaces. Present on window_update notifications to indicate progression (e.g., 'live' when reporting C3 data that supersedes live-only numbers). Absent on the first report for a period. Buyers should replace stored data for the superseded window with this report's data.", "examples": [ "live", "c3" ] }, "missing_metrics": { "type": "array", "description": "Metrics that the binding reporting contract declared but that are NOT populated in this report. Reconciliation source: when `package.committed_metrics` is present, `missing_metrics` is computed against entries where `committed_at < reporting_period.end` — independent of subsequent product mutations and respecting the commitment timestamp on each entry (a metric committed mid-flight is only flagged missing in reports for periods after its commitment). When `package.committed_metrics` is absent, fall back to the product's current `reporting_capabilities.available_metrics` (no timestamp filter). Empty array (or absent) indicates clean delivery against the contract. Non-empty signals an accountability breach — the seller committed to the metric but did not produce the value here. Sellers MUST exclude metrics that are not yet measurable for the current `measurement_window` (e.g., post-IVT counts during the live window) — those will appear (or not) when a wider window supersedes this report via `supersedes_window`. Each entry uses an explicit `scope` discriminator: `standard` for entries from the closed `available-metric.json` enum, `vendor` for vendor-defined metrics anchored on a BrandRef. Symmetric with `committed_metrics`.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/missing-metric.json" }, "examples": [ [], [ { "scope": "standard", "metric_id": "completed_views" } ], [ { "scope": "standard", "metric_id": "completed_views" }, { "scope": "vendor", "vendor": { "domain": "attentionvendor.example" }, "metric_id": "attention_units" } ] ] }, "by_catalog_item": { "type": "array", "description": "Delivery by catalog item within this package. Available for catalog-driven packages when the seller supports item-level reporting.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/catalog-item-delivery-metrics.json" } }, "by_creative": { "type": "array", "description": "Metrics broken down by creative within this package. Available when the seller supports creative-level reporting.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/creative-delivery-metrics.json" } }, "by_keyword": { "type": "array", "description": "Metrics broken down by keyword within this package. One row per (keyword, match_type) pair — the same keyword with different match types appears as separate rows. Keyword-grain only: rows reflect aggregate performance of each targeted keyword, not individual search queries. Rows may not sum to package totals when a single impression is attributed to the triggering keyword only. Available for search and retail media packages when the seller supports keyword-level reporting.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/keyword-delivery-metrics.json" } }, "by_geo": { "type": "array", "description": "Delivery by geographic area within this package. Available when the buyer requests geo breakdown via reporting_dimensions and the seller supports it. Each dimension's rows are independent slices that should sum to the package total.", "items": { "$ref": "/schemas/3.1.0-rc.4/core/geo-delivery-metrics.json" } }, "by_geo_truncated": { "type": "boolean", "description": "Whether by_geo was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_geo is present (false means the list is complete)." }, "by_device_type": { "type": "array", "description": "Delivery by device form factor within this package. Available when the buyer requests device_type breakdown via reporting_dimensions and the seller supports it.", "items": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "properties": { "device_type": { "$ref": "/schemas/3.1.0-rc.4/enums/device-type.json", "description": "Device form factor (desktop, mobile, tablet, ctv, dooh, unknown)" } }, "required": [ "device_type", "impressions", "spend" ] } ] } }, "by_device_type_truncated": { "type": "boolean", "description": "Whether by_device_type was truncated. Sellers MUST return this flag whenever by_device_type is present (false means the list is complete)." }, "by_device_platform": { "type": "array", "description": "Delivery by operating system within this package. Available when the buyer requests device_platform breakdown via reporting_dimensions and the seller supports it. Useful for CTV campaigns where tvOS vs Roku OS vs Fire OS matters.", "items": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "properties": { "device_platform": { "$ref": "/schemas/3.1.0-rc.4/enums/device-platform.json", "description": "Operating system platform" } }, "required": [ "device_platform", "impressions", "spend" ] } ] } }, "by_device_platform_truncated": { "type": "boolean", "description": "Whether by_device_platform was truncated. Sellers MUST return this flag whenever by_device_platform is present (false means the list is complete)." }, "by_audience": { "type": "array", "description": "Delivery by audience segment within this package. Available when the buyer requests audience breakdown via reporting_dimensions and the seller supports it. Only 'synced' audiences are directly targetable via the targeting overlay; other sources are informational.", "items": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "properties": { "audience_id": { "type": "string", "description": "Audience segment identifier. For 'synced' source, matches audience_id from sync_audiences. For other sources, seller-defined.", "x-entity": "audience" }, "audience_source": { "$ref": "/schemas/3.1.0-rc.4/enums/audience-source.json", "description": "Origin of the audience segment (synced, platform, third_party, lookalike, retargeting, unknown)" }, "audience_name": { "type": "string", "description": "Human-readable audience segment name" } }, "required": [ "audience_id", "audience_source", "impressions", "spend" ] } ] } }, "by_audience_truncated": { "type": "boolean", "description": "Whether by_audience was truncated. Sellers MUST return this flag whenever by_audience is present (false means the list is complete)." }, "by_placement": { "type": "array", "description": "Delivery by placement within this package. Available when the buyer requests placement breakdown via reporting_dimensions and the seller supports it. Placement IDs reference the product's placements array.", "items": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "properties": { "placement_id": { "type": "string", "description": "Placement identifier from the product's placements array" }, "placement_name": { "type": "string", "description": "Human-readable placement name" } }, "required": [ "placement_id", "impressions", "spend" ] } ] } }, "by_placement_truncated": { "type": "boolean", "description": "Whether by_placement was truncated. Sellers MUST return this flag whenever by_placement is present (false means the list is complete)." }, "daily_breakdown": { "type": "array", "description": "Day-by-day delivery for this package. Only present when include_package_daily_breakdown is true in the request. Enables per-package pacing analysis and line-item monitoring.", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date (YYYY-MM-DD)" }, "impressions": { "type": "number", "description": "Daily impressions for this package", "minimum": 0 }, "spend": { "type": "number", "description": "Daily spend for this package", "minimum": 0 }, "conversions": { "type": "number", "description": "Daily conversions for this package", "minimum": 0 }, "conversion_value": { "type": "number", "description": "Daily conversion value for this package", "minimum": 0 }, "roas": { "type": "number", "description": "Daily return on ad spend (conversion_value / spend)", "minimum": 0 }, "new_to_brand_rate": { "type": "number", "description": "Daily fraction of conversions from first-time brand buyers (0 = none, 1 = all)", "minimum": 0, "maximum": 1 } }, "required": [ "date", "impressions", "spend" ], "additionalProperties": true } } }, "required": [ "package_id", "spend", "pricing_model", "rate", "currency" ] } ] } }, "windows": { "type": "array", "description": "Per-window delivery slices over the reporting period at the requested time_granularity. Only present when the request set time_granularity and include_window_breakdown: true. Each slice mirrors what reporting_webhook would have delivered for the same window — buyers who missed webhook fires can reconstruct identical data by reading this array. Slice rows are ordered by window_start ascending; consecutive rows are contiguous (each row's window_end equals the next row's window_start) and partition the requested date range at the chosen granularity. Sellers MUST exclude this field when time_granularity is omitted; when set, sellers MUST honor pulls at any granularity in reporting_capabilities.windowed_pull_granularities (otherwise return UNSUPPORTED_GRANULARITY). See snapshot-and-log Rule 4 for the two-paths-parity contract this surface anchors.", "items": { "type": "object", "properties": { "window_start": { "type": "string", "format": "date-time", "description": "ISO 8601 start of the window slice (inclusive). UTC." }, "window_end": { "type": "string", "format": "date-time", "description": "ISO 8601 end of the window slice (exclusive). The next row's window_start equals this value when slices are contiguous." }, "totals": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" } ], "description": "Aggregate metrics for this window slice across all packages. Shape-aligned with reporting_webhook fire payloads at the same granularity." }, "by_package": { "type": "array", "description": "Per-package metrics for this window slice. Same shape as the parent media_buy_deliveries[].by_package row but scoped to the window. Sellers MAY omit when per-package window-level data is unavailable; when present, package_id values MUST match the parent by_package entries.", "items": { "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/delivery-metrics.json" }, { "type": "object", "properties": { "package_id": { "type": "string", "description": "Seller's package identifier", "x-entity": "package" } }, "required": [ "package_id" ] } ] } }, "is_final": { "type": "boolean", "description": "Whether the slice data is final for this window. Same semantics as the per-package is_final flag — when false, a later read may return revised numbers for the same window as measurement matures (broadcast C3 → C7, post-IVT filtering, etc.)." }, "measurement_window": { "type": "string", "maxLength": 50, "description": "Which measurement-window stage this slice represents (e.g., 'live', 'c3', 'c7'), referencing a window_id from the product's reporting_capabilities.measurement_windows. Absent when the data is not phased." } }, "required": [ "window_start", "window_end", "totals" ] } }, "daily_breakdown": { "type": "array", "description": "Day-by-day delivery", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date (YYYY-MM-DD)" }, "impressions": { "type": "number", "description": "Daily impressions", "minimum": 0 }, "spend": { "type": "number", "description": "Daily spend", "minimum": 0 }, "conversions": { "type": "number", "description": "Daily conversions", "minimum": 0 }, "conversion_value": { "type": "number", "description": "Daily conversion value", "minimum": 0 }, "roas": { "type": "number", "description": "Daily return on ad spend (conversion_value / spend)", "minimum": 0 }, "new_to_brand_rate": { "type": "number", "description": "Daily fraction of conversions from first-time brand buyers (0 = none, 1 = all)", "minimum": 0, "maximum": 1 } }, "required": [ "date", "impressions", "spend" ], "additionalProperties": true } } }, "required": [ "media_buy_id", "status", "totals", "by_package" ], "additionalProperties": true } }, "errors": { "type": "array", "description": "Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)", "items": { "$ref": "/schemas/3.1.0-rc.4/core/error.json" } }, "sandbox": { "type": "boolean", "description": "When true, this response contains simulated data from sandbox mode." }, "context": { "$ref": "/schemas/3.1.0-rc.4/core/context.json" }, "ext": { "$ref": "/schemas/3.1.0-rc.4/core/ext.json" } }, "required": [ "reporting_period", "currency", "media_buy_deliveries" ], "additionalProperties": true }