{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/3.1.0-rc.4/account/report-usage-request.json", "title": "Report Usage Request", "description": "Reports how a vendor's service was consumed after campaign delivery. Used by orchestrators (DSPs, storefronts) to inform vendor agents (signals, governance, creative, or — when the receiving agent is the seller of the media buy itself — a sales agent for buyer-attested or vendor-attested billing reconciliation) what was used so the receiver can track earned revenue and verify billing. Records can span multiple accounts and campaigns in a single request. When the buy's `measurement_terms.billing_measurement.vendor` names a party other than the seller's own ad server, that party (or the buyer on its behalf) pushes final measurements via this task; the seller invoices against those final records. See [Billing authority](/docs/media-buy/advanced-topics/billing-authority) for the end-to-end flow.", "type": "object", "allOf": [ { "$ref": "/schemas/3.1.0-rc.4/core/version-envelope.json" } ], "x-mutates-state": true, "properties": { "idempotency_key": { "type": "string", "description": "Client-generated unique key for this request. If a request with the same key has already been accepted, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request. Prevents duplicate billing on retries." }, "reporting_period": { "$ref": "/schemas/3.1.0-rc.4/core/datetime-range.json", "description": "The time range covered by this usage report. Applies to all records in the request." }, "usage": { "type": "array", "description": "One or more usage records. Each record is self-contained: it carries its own account, allowing a single request to span multiple accounts.", "minItems": 1, "items": { "type": "object", "properties": { "account": { "$ref": "/schemas/3.1.0-rc.4/core/account-ref.json", "description": "Account for this usage record." }, "media_buy_id": { "type": "string", "description": "Seller-assigned media buy identifier. Links this usage record to a specific media buy.", "x-entity": "media_buy" }, "vendor_cost": { "type": "number", "minimum": 0, "description": "Amount owed to the vendor for this record, denominated in currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code." }, "pricing_option_id": { "type": "string", "description": "Pricing option identifier from the vendor's discovery response (e.g., get_signals, list_content_standards). The vendor uses this to verify the correct rate was applied.", "x-entity": "vendor_pricing_option" }, "impressions": { "type": "integer", "minimum": 0, "description": "Impressions delivered using this vendor service." }, "media_spend": { "type": "number", "minimum": 0, "description": "Media spend in currency for the period. Required when a percent_of_media pricing model was used, so the vendor can verify the applied rate." }, "signal_agent_segment_id": { "type": "string", "description": "Signal identifier from get_signals. Required for signals agents.", "x-entity": "signal_activation_id" }, "standards_id": { "type": "string", "description": "Content standards configuration identifier. Required for governance agents.", "x-entity": "content_standards" }, "rights_id": { "type": "string", "description": "Rights grant identifier from acquire_rights. Required for brand/rights agents. Links usage records to specific rights grants for cap tracking, billing verification, and overage calculation.", "x-entity": "rights_grant" }, "creative_id": { "type": "string", "description": "Creative identifier from build_creative or list_creatives. Required for creative agents. Links usage records to specific creatives for billing verification.", "x-entity": "creative" }, "property_list_id": { "type": "string", "description": "Property list identifier from list_property_lists. Required for property list agents. Links usage records to specific property lists for billing verification.", "x-entity": "property_list" }, "final": { "type": "boolean", "description": "Whether this usage record represents the reporter's final, billing-authoritative numbers for the reporting period. **Absent means unknown** — the reporter has not declared finality on this record. Set `true` only when the reporter has actually settled the numbers (e.g., 3PAS month-end close after SIVT scrubbing, conversion dedup, and view-through windows have closed; vendor file post-C7 for broadcast). Set `false` when pushing preliminary measurements (daily pacing pushes, intra-period progress) that are still settling. Receivers MUST NOT invoice on `final: false` records, and MUST NOT invoice on records where `final` is absent for buys whose `measurement_terms.billing_measurement` names this reporter as authoritative — request a final record first. Receivers MAY invoice on absent for buys with no `measurement_terms.billing_measurement` (3.0-style usage where the receiver treats reports as authoritative on receipt) and for non-media-buy variants (signals, governance, creative, brand — domains with no provisional state concept). When the same `(account, media_buy_id, reporting_period)` is later reported with `final: true`, that record supersedes any prior records for the period." }, "finalized_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which the reporter considered these numbers final. Present only when `final: true`. Anchors any deadline declared in the buy's `measurement_terms.billing_measurement.finalization_deadline_hours`." }, "measurement_window": { "type": "string", "maxLength": 50, "description": "Which measurement window this record represents, referencing a window_id from the product's reporting_capabilities.measurement_windows or from `measurement_terms.billing_measurement.measurement_window`. Examples: 'c7' for broadcast TV, 'post_sivt' for digital post-IVT, 'downloads_30d' for podcast. When absent, the record is not windowed (standard digital reporting). When the buy's `measurement_terms.billing_measurement.measurement_window` is set, reporters SHOULD include `measurement_window` so the receiver can reconcile against the correct stage.", "examples": [ "live", "c3", "c7", "post_ivt", "post_sivt", "downloads_30d" ] } }, "required": [ "account", "vendor_cost", "currency" ], "additionalProperties": true } }, "context": { "$ref": "/schemas/3.1.0-rc.4/core/context.json" }, "ext": { "$ref": "/schemas/3.1.0-rc.4/core/ext.json" } }, "required": [ "idempotency_key", "reporting_period", "usage" ], "additionalProperties": true, "examples": [ { "description": "Signal usage for a single campaign", "data": { "idempotency_key": "550e8400-e29b-41d4-a716-446655440000", "reporting_period": { "start": "2025-03-01T00:00:00Z", "end": "2025-03-31T23:59:59Z" }, "usage": [ { "account": { "account_id": "acct_pinnacle_signals" }, "signal_agent_segment_id": "luxury_auto_intenders", "pricing_option_id": "po_lux_auto_cpm", "impressions": 4200000, "media_spend": 21000, "vendor_cost": 2100, "currency": "USD" } ] } }, { "description": "Multi-account batch across two campaigns", "data": { "idempotency_key": "8b7a9c2d-3456-4789-abcd-ef0123456789", "reporting_period": { "start": "2025-03-01T00:00:00Z", "end": "2025-03-31T23:59:59Z" }, "usage": [ { "account": { "account_id": "acct_pinnacle_signals" }, "signal_agent_segment_id": "luxury_auto_intenders", "pricing_option_id": "po_lux_auto_cpm", "impressions": 2100000, "vendor_cost": 1050, "currency": "USD" }, { "account": { "account_id": "acct_nova" }, "signal_agent_segment_id": "eco_conscious_shoppers", "pricing_option_id": "po_eco_cpm", "impressions": 800000, "vendor_cost": 400, "currency": "USD" } ] } } ] }