> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Update media buy > Partially update a single media buy, resolved top-level by mediaBuyId — the owning campaign is resolved server-side, consistent with GET /media-buys/{mediaBuyId}. Rejected outright (not a warning) when it would violate a campaign invariant: currency (a product's replacement pricing option settles in a different currency than this buy), budget headroom (the update would exceed the campaign's remaining all-in budget), or mode compatibility (the campaign is directed and has no platform-managed update path). A flight date outside the campaign's current window is not a failure — the campaign flight is widened to cover it and a warning is returned. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml patch /media-buys/{mediaBuyId} openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /media-buys/{mediaBuyId}: patch: tags: - Campaigns summary: Update media buy description: >- Partially update a single media buy, resolved top-level by mediaBuyId — the owning campaign is resolved server-side, consistent with GET /media-buys/{mediaBuyId}. Rejected outright (not a warning) when it would violate a campaign invariant: currency (a product's replacement pricing option settles in a different currency than this buy), budget headroom (the update would exceed the campaign's remaining all-in budget), or mode compatibility (the campaign is directed and has no platform-managed update path). A flight date outside the campaign's current window is not a failure — the campaign flight is widened to cover it and a warning is returned. operationId: updateMediaBuy parameters: - in: path name: mediaBuyId schema: type: string minLength: 1 description: Buyer media buy ID example: mb_ETBn4gJ9Wu required: true description: Buyer media buy ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMediaBuyRequest' responses: '200': description: Update media buy content: application/json: schema: $ref: '#/components/schemas/UpdateMediaBuyResponse' '400': description: >- Validation failed: the campaign is directed, the campaign is completed/archived/cancelled, the update would exceed the campaign's remaining budget headroom, or a product's replacement pricing option settles in a different currency than this buy. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Caller is not a buyer — the route is mounted behind the buyer role guard. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No media buy with this id owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: The media buy is in a terminal status and can no longer be updated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: UpdateMediaBuyRequest: type: object properties: name: description: Updated media buy name type: string minLength: 1 maxLength: 255 packages: description: Per-package updates (for media buys with deployed packages) type: array items: $ref: '#/components/schemas/UpdateMediaBuyPackageInput' products: description: >- Product updates — additive (existing products not listed are preserved). type: array items: $ref: '#/components/schemas/UpdateMediaBuyProductInput' start_time: description: >- "asap" or ISO 8601 date-time. A value earlier than the campaign's current flight start does not fail the request — it is applied and surfaced as a warning, and the campaign flight is widened to cover it. type: string end_time: description: >- ISO 8601 date-time. A value later than the campaign's current flight end does not fail the request — it is applied and surfaced as a warning, and the campaign flight is widened to cover it. type: string optimization_goals: description: >- Replace media-buy-level optimization goals; applied to every package at execution time. Pass an empty array to clear all goals. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: anyOf: - type: object properties: {} additionalProperties: {} - type: object properties: {} additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - vendor - metric_id additionalProperties: {} creative_ids: description: >- Explicit creative IDs to attach to this media buy. Pass an empty array to clear all creatives. type: array items: type: string minLength: 1 updated_reason: description: Reason for the update (stored with the new version) type: string maxLength: 1000 additionalProperties: false description: >- Partial update for a single media buy, resolved top-level by mediaBuyId. Rejected outright (not warned) when it would violate a campaign invariant: currency (a product's replacement pricing option settles in a different currency), budget headroom (the update would exceed the campaign's remaining all-in budget), or mode compatibility (the campaign is directed — its mirrored media buy has no platform-managed update path). UpdateMediaBuyResponse: type: object properties: mediaBuy: $ref: '#/components/schemas/BuyerMediaBuy' warnings: description: >- Non-blocking notices about this update, e.g. a flight date fell outside the campaign window (the campaign window was widened to cover it, rather than failing the request). type: array items: type: string required: - mediaBuy additionalProperties: false description: >- The updated media buy (why-visibility fields included) plus any non-blocking warnings. ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response UpdateMediaBuyPackageInput: type: object properties: packageId: type: string minLength: 1 description: Package ID to update budget: description: Updated budget amount type: number minimum: 0 exclusiveMinimum: true pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number startTime: description: >- Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ endTime: description: >- Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ targetingOverlay: type: object properties: audience_include: anyOf: - minItems: 1 type: array items: type: string description: >- Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null audience_exclude: anyOf: - minItems: 1 type: array items: type: string description: >- Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null geo_countries: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). - type: string nullable: true enum: - null geo_regions: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. - type: string nullable: true enum: - null additionalProperties: false description: >- Per-dimension targeting patch. Omit a field to preserve its current value, pass null to clear it, or pass a value to replace it. Not every adapter supports every field at update time; an unsupported field is rejected with UNSUPPORTED_TARGETING_DIMENSION. required: - packageId additionalProperties: false description: Per-package update for a media buy with deployed packages UpdateMediaBuyProductInput: type: object properties: productId: type: string minLength: 1 description: Product ID (must already be on this media buy) storefrontId: description: Exact Storefront identity returned by discovery type: string pattern: ^[1-9]\d*$ inventorySourceId: description: >- Exact inventory-source identity returned by discovery; null identifies Storefront-owned inventory nullable: true type: string pattern: ^[1-9]\d*$ pricingOptionId: description: >- The replacement pricing option must resolve to this media buy's existing settlement currency — update_media_buy does not re-split a buy across sales agents or currencies. type: string buyerRef: description: >- Line-item handle from the media buy read. Required to target one line item when the same product appears more than once on the buy; omit when the product is unique. type: string minLength: 1 maxLength: 255 budget: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: >- Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: >- Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel. example: '123456789012345' type: string minLength: 1 instagramActorId: description: >- Meta Instagram account ID for Instagram Direct destinations (Instagram Direct Conversations, Instagram-based Lead Generation). Required when the connected ad account has more than one authorized Instagram account — unlike pageId, the error does not enumerate candidate IDs; obtain the Instagram Business Account ID from Meta Business Settings. Omit when the account has exactly one authorized Instagram account (the server selects it automatically). example: '17841400000000000' type: string minLength: 1 welcomeMessageFlowId: description: >- Meta welcome message flow ID for lead-to-message destinations (Messenger, Instagram Direct, and WhatsApp Lead Generation). Required for these products — pass one of the welcome-message-flow candidates returned by account resource readiness in the discovery/get_products response. example: '1122334455667788' type: string minLength: 1 required: - productId additionalProperties: false description: >- Product update — additive (existing products not listed are preserved). Use remove: true to delete a product. Does not add brand-new product selections; use create_media_buys for that. BuyerMediaBuy: type: object properties: mediaBuyId: type: string description: Buyer media buy ID example: mb_ETBn4gJ9Wu name: type: string description: Media buy name channelGroup: description: >- Campaign channel group that compiled into this media buy. Absent for legacy and ungrouped buys. type: object properties: channelGroupId: type: string name: type: string required: - channelGroupId - name additionalProperties: false campaignId: description: >- The campaign this media buy belongs to. Use it with get_campaign (optionally narrowed with ?mediaBuyId=) to read packages, products, and delivery for this buy. example: cmp_ETBn4gJ9Wu type: string status: type: string description: >- Interchange media buy status (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, COMPLETED, CANCELED, FAILED, REJECTED). example: PENDING_APPROVAL archivedAt: description: >- When this media buy was archived (ISO 8601). Archiving controls visibility and preserves the media buy status. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ pendingAt: description: >- Which layer the buy is parked at; only present while status is PENDING_APPROVAL. Use pendingReason for the specific wait. type: string enum: - storefront - salesagent - unknown pendingChange: description: >- A submitted change that has not yet reached the delivering buy. Every other field on this object describes what is LIVE, so this is the only place a queued change surfaces. Absent when there is nothing pending. allOf: - $ref: '#/components/schemas/MediaBuyPendingChange' pendingReason: description: >- Why the buy is not delivering yet, rolled up to the most-blocking wait across its legs. An annotation derived from persisted forwarding state — never a status. Absent when the buy is delivering, terminal, or not storefront-routed. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: description: >- When the current wait began (ISO 8601). Present when pendingReason is set and the start of the wait is known. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ errorCode: description: >- Buyer-safe structured error code when forwarding failed or the buy was rejected. Internal platform codes are mapped to this set and never emitted raw. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' errorOwner: description: >- Which party owns fixing the error. Present whenever errorCode is present. allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' sourceMessage: description: >- The source's rejection or moderation message, when one was provided — whitespace-collapsed, truncated, and known upstream identifiers removed. type: string forwardedAt: description: >- When the buy was forwarded to its inventory source(s) (ISO 8601). Absent when it has not been forwarded. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ buyerReference: description: >- Support reference for this buy (`sf::`). Quote it with the request timestamp when contacting the seller or Scope3 support. example: sf:42:sf_mb_1783031864469_8pbc8mmr type: string startTime: description: 'When this media buy starts: "asap" or an ISO 8601 date-time.' type: string endTime: description: When this media buy ends (ISO 8601). type: string optimizationGoals: description: >- Optimization goals applied to this media buy and its packages. Absent when no goals are configured. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: anyOf: - type: object properties: {} additionalProperties: {} - type: object properties: {} additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - vendor - metric_id additionalProperties: {} pausedBy: nullable: true description: >- Who paused this media buy: 'buyer' for a direct per-buy pause, 'campaign' for a campaign-cascade pause. Absent or null when the buy is not currently paused or was paused before provenance tracking. type: string enum: - buyer - campaign createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the media buy was created (ISO 8601) updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the media buy was last updated (ISO 8601) required: - mediaBuyId - name - status - createdAt - updatedAt additionalProperties: false description: >- A single media buy with its optimization goals and why-visibility annotation (pendingReason, errorCode, forwardedAt, buyerReference). Use get_campaign for packages, products, and delivery. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object MediaBuyPendingChange: type: object properties: status: type: string description: >- Lifecycle status of the pending change itself, typically PENDING_APPROVAL. This is NOT the status of the buy: the buy keeps its own top-level status, which reflects what is delivering now. example: PENDING_APPROVAL pendingAt: description: >- Which layer the pending change is parked at. 'storefront' = waiting on the storefront operator's manual approval, 'salesagent' = the inventory source is still processing it, 'unknown' = indeterminate. type: string enum: - storefront - salesagent - unknown reason: description: >- Reason recorded when the change was submitted, when one was supplied. example: Extended to 8/11 with W5+W6 gross budget type: string proposalId: description: >- ID of the pending update proposal awaiting seller approval, present when the change is routed through the async approval flow. Pass to DELETE /api/v2/buyer/update-proposals/{proposalId} to cancel it. example: uprop_abc1234567 type: string differences: type: object properties: endTime: description: Flight end date change (ISO 8601). type: object properties: live: description: The value currently in effect on the delivering buy. type: string proposed: description: The value the pending change would set. type: string additionalProperties: false budget: description: >- Total budget change in the buy's currency, summed across its packages. type: object properties: live: description: The value currently in effect on the delivering buy. type: number proposed: description: The value the pending change would set. type: number additionalProperties: false creatives: description: >- Creative IDs currently attached compared with the proposed attachment set. type: object properties: live: description: The value currently in effect on the delivering buy. type: array items: type: string proposed: description: The value the pending change would set. type: array items: type: string additionalProperties: false additionalProperties: false description: >- Only the fields whose pending value differs from live appear here. An empty object means a pending change exists whose comparable fields already match live. required: - status - differences additionalProperties: false description: >- A buyer-submitted change that has been accepted by Interchange but has NOT yet taken effect on the delivering buy. Its presence is the signal that this buy has an unapplied change; absence means everything reported is live. Never treat these values as delivering. MediaBuyPendingReason: type: string enum: - forward_failed_needs_correction - forward_failed_retrying - awaiting_storefront_approval - awaiting_source_moderation - no_creatives_attached - source_rejected_creatives - creative_processing_at_source - awaiting_creative_approval - accepted_awaiting_trafficking - scheduled_not_started description: >- Why a not-yet-delivering media buy is waiting, and implicitly whose side owns the wait. A platform-derived annotation — never a status value. awaiting_storefront_approval / awaiting_source_moderation / creative_processing_at_source / awaiting_creative_approval = the seller side owns the wait; no_creatives_attached / source_rejected_creatives = the buyer owns it (attach or fix creatives); forward_failed_retrying / forward_failed_needs_correction = the platform owns it; accepted_awaiting_trafficking / scheduled_not_started = nothing is wrong, the buy is queued or scheduled. BuyerMediaBuyErrorCode: type: string enum: - product_no_longer_available - source_rejected - storefront_rejected - source_unavailable - invalid_request - quote_expired - platform_error description: >- Buyer-safe structured error code for a media buy that failed to forward or was rejected. Paired with errorOwner (who owns the fix) and, when the source provided one, a sanitized human-readable message. MediaBuyErrorOwner: type: string enum: - buyer_input - platform - seller description: >- Which party owns fixing the error: buyer_input (the request needs a correction from the buyer), platform (Scope3 owns the fault), seller (the storefront or its source made the decision or is unavailable). securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````