Interface ProposalPurchase

interface ProposalPurchase {
    product_id: string;
    pricing_option_id: string;
    pricing?:
        | {
            pricing_option_id: string;
            pricing_model: | "cpm"
            | "vcpm"
            | "cpc"
            | "cpcv"
            | "cpv"
            | "cpp"
            | "cpa"
            | "revenue_share"
            | "flat_rate"
            | "time";
            currency: string;
            fixed_price?: number;
            floor_price?: number;
            price_guidance?: PriceGuidance;
            min_spend_per_package?: number;
            price_breakdown?: PriceBreakdown;
            eligible_adjustments?: PriceAdjustmentKind[];
            parameters?: {};
            event_type?: EventType;
            custom_event_name?: string;
            event_source_id?: string;
            commission_rate?: number;
            commission_basis_description?: string;
        }
        | ProposalResolvedPricing;
    format_option_refs?: [FormatOptionReference, ...FormatOptionReference[]];
    catalog_ids?: [string, ...string[]];
    budget?: number;
    daily_budget_cap?: number;
    min_spend_target?: number;
    impressions?: number;
    start_time?: string;
    end_time?: string;
    pacing?: Pacing;
    bidding?: {
        automatic?: true;
        bid_amount?: number;
        max_bid?: number;
        cost_per?: { amount: number; strength: "cap" | "target" };
        roas?: { value: number; strength: "target" | "floor" };
    };
    targeting_overlay?: TargetingOverlay;
    optimization_goals?: [
        CanonicalOptimizationGoal,
        ...CanonicalOptimizationGoal[],
    ];
    audience_evidence_requirements?: {
        requirement_mode: "required"
        | "preferred";
        evidence_presence: "required" | "when_available";
        accepted_methodologies?: [
            AudienceEvidenceMethodology,
            ...AudienceEvidenceMethodology[],
        ];
        excluded_methodologies?: [
            AudienceEvidenceMethodology,
            ...AudienceEvidenceMethodology[],
        ];
        accepted_evidence_types?: [
            "forecast"
            | "measured"
            | "seller_declared",
            ...("forecast" | "measured" | "seller_declared")[],
        ];
        accepted_providers?: [BrandKey, ...BrandKey[]];
        excluded_providers?: [BrandKey, ...BrandKey[]];
        accepted_subject_types?: [AudienceSubjectType, ...AudienceSubjectType[]];
        accepted_resolution_methods?: [
            AudienceResolutionMethod,
            ...AudienceResolutionMethod[],
        ];
        minimum_confidence?: number;
        maximum_age?: Duration & {
            unit?: "seconds"
            | "minutes"
            | "hours"
            | "days";
        };
        methodology_documentation_required?: boolean;
        independent_attestation_required?: boolean;
        accepted_attestation_issuers?: [
            | { type: "brand"; brand: BrandKey; ext?: ExtensionObject }
            | { type: "agent"; agent_url: string; ext?: ExtensionObject }
            | { type: "origin"; origin: string; ext?: ExtensionObject },
            ...(
                | { type: "brand"; brand: BrandKey; ext?: ExtensionObject }
                | { type: "agent"; agent_url: string; ext?: ExtensionObject }
                | { type: "origin"; origin: string; ext?: ExtensionObject }
            )[],
        ];
        accepted_attestation_claim_types?: [string, ...string[]];
        ext?: ExtensionObject;
    };
    audience_evidence_pins?: [AudienceEvidencePin, ...AudienceEvidencePin[]];
    agency_estimate_number?: string;
    context?: ContextObject;
    ext?: ExtensionObject;
    measurement_terms?: ProductPurchaseMeasurementTerms;
    performance_standards?: [
        CanonicalPerformanceStandard,
        ...CanonicalPerformanceStandard[],
    ];
}

Properties

product_id

product_id: string

pricing_option_id

pricing_option_id: string

`Optional`pricing

pricing?:
    | {
        pricing_option_id: string;
        pricing_model: | "cpm"
        | "vcpm"
        | "cpc"
        | "cpcv"
        | "cpv"
        | "cpp"
        | "cpa"
        | "revenue_share"
        | "flat_rate"
        | "time";
        currency: string;
        fixed_price?: number;
        floor_price?: number;
        price_guidance?: PriceGuidance;
        min_spend_per_package?: number;
        price_breakdown?: PriceBreakdown;
        eligible_adjustments?: PriceAdjustmentKind[];
        parameters?: {};
        event_type?: EventType;
        custom_event_name?: string;
        event_source_id?: string;
        commission_rate?: number;
        commission_basis_description?: string;
    }
    | ProposalResolvedPricing

Resolved pricing is required in accepted snapshots but optional on direct-purchase inputs.

`Optional`format_option_refs

format_option_refs?: [FormatOptionReference, ...FormatOptionReference[]]

`Optional`catalog_ids

catalog_ids?: [string, ...string[]]

`Optional`budget

budget?: number

`Optional`daily_budget_cap

daily_budget_cap?: number

`Optional`min_spend_target

min_spend_target?: number

`Optional`impressions

impressions?: number

`Optional`start_time

start_time?: string

`Optional`end_time

end_time?: string

`Optional`pacing

pacing?: Pacing

`Optional`bidding

bidding?: {
    automatic?: true;
    bid_amount?: number;
    max_bid?: number;
    cost_per?: { amount: number; strength: "cap" | "target" };
    roas?: { value: number; strength: "target" | "floor" };
}

Type Declaration

Optionalautomatic?: true

Explicitly use seller/provider automatic bidding at this authored scope. At package scope this is a complete override of a media-buy policy, not inheritance. It MUST be the only field in the block and MUST be preserved on readback.
Optionalbid_amount?: number

Manual auction bid denominated in the media-buy currency and expressed per the selected pricing option's auction unit. For example, a CPM option interprets the amount per thousand impressions. This is the amount submitted to the auction, not a promise that the clearing price equals it. Requires an auction-priced pricing option whose currency equals the media-buy currency.
Optionalmax_bid?: number

Hard per-auction ceiling denominated in the media-buy currency and expressed per the selected pricing option's auction unit. This is the only canonical hard auction ceiling and MUST NOT be translated into an average outcome-cost control. Requires an auction-priced pricing option whose currency equals the media-buy currency. May stand alone or supplement cost_per/roas only when the relevant scope capability advertises that combination.
Optionalcost_per?: { amount: number; strength: "cap" | "target" }

Average cost control per result of the scope-bound primary optimization goal. At seller-optimized media-buy scope it binds to budget_allocation.optimization_goals; at package scope it binds to that package's optimization_goals; at fixed media-buy scope it binds independently to each inheriting package and is valid only when their primary-goal result units are compatible. Metric goals are compatible only when metric and every result-defining qualifier match; vendor_metric goals only when vendor and metric_id match; event goals only when the event_type/custom_event_name set and resolved attribution_window match. Primary is the earliest array entry among goals tied for the lowest explicit numeric priority; unprioritized goals follow explicitly prioritized goals; when all priorities are absent, the first entry is primary.
- amount: number
  
  Average cost amount per scope-bound primary-goal result, denominated in the media-buy currency.
- strength: "cap" | "target"
  
  cap optimizes for an average at or below the amount and accepts underdelivery when necessary; target optimizes around the amount while balancing volume and spend. Neither is a per-result or per-auction guarantee.
Optionalroas?: { value: number; strength: "target" | "floor" }

Dimensionless return-on-ad-spend control bound to the same scope-specific primary goal rules as cost_per. The bound goal must be value-bearing; a fixed media-buy default requires a value-bearing primary goal on every inheriting package. Every referenced value-bearing event source MUST declare value_currencies containing the media-buy currency. The seller validates this at buy creation; each buy consumes only exact-currency records, while other declared currencies remain available to other buys. Sellers MUST NOT perform currency conversion.
- value: number
  
  Return per unit of ad spend; 4 means 4 units of value per 1 unit spent.
- strength: "target" | "floor"
  
  floor prefers underdelivery to knowingly optimizing below the requested return; target optimizes around the requested return. Neither guarantees realized return.

`Optional`targeting_overlay

targeting_overlay?: TargetingOverlay

`Optional`optimization_goals

optimization_goals?: [CanonicalOptimizationGoal, ...CanonicalOptimizationGoal[]]

`Optional`audience_evidence_requirements

audience_evidence_requirements?: {
    requirement_mode: "required" | "preferred";
    evidence_presence: "required" | "when_available";
    accepted_methodologies?: [
        AudienceEvidenceMethodology,
        ...AudienceEvidenceMethodology[],
    ];
    excluded_methodologies?: [
        AudienceEvidenceMethodology,
        ...AudienceEvidenceMethodology[],
    ];
    accepted_evidence_types?: [
        "forecast"
        | "measured"
        | "seller_declared",
        ...("forecast" | "measured" | "seller_declared")[],
    ];
    accepted_providers?: [BrandKey, ...BrandKey[]];
    excluded_providers?: [BrandKey, ...BrandKey[]];
    accepted_subject_types?: [AudienceSubjectType, ...AudienceSubjectType[]];
    accepted_resolution_methods?: [
        AudienceResolutionMethod,
        ...AudienceResolutionMethod[],
    ];
    minimum_confidence?: number;
    maximum_age?: Duration & {
        unit?: "seconds"
        | "minutes"
        | "hours"
        | "days";
    };
    methodology_documentation_required?: boolean;
    independent_attestation_required?: boolean;
    accepted_attestation_issuers?: [
        | { type: "brand"; brand: BrandKey; ext?: ExtensionObject }
        | { type: "agent"; agent_url: string; ext?: ExtensionObject }
        | { type: "origin"; origin: string; ext?: ExtensionObject },
        ...(
            | { type: "brand"; brand: BrandKey; ext?: ExtensionObject }
            | { type: "agent"; agent_url: string; ext?: ExtensionObject }
            | { type: "origin"; origin: string; ext?: ExtensionObject }
        )[],
    ];
    accepted_attestation_claim_types?: [string, ...string[]];
    ext?: ExtensionObject;
}

Type Declaration

requirement_mode: "required" | "preferred"
evidence_presence: "required" | "when_available"
Optionalaccepted_methodologies?: [AudienceEvidenceMethodology, ...AudienceEvidenceMethodology[]]

Min Items
1
Optionalexcluded_methodologies?: [AudienceEvidenceMethodology, ...AudienceEvidenceMethodology[]]

Min Items
1
Optionalaccepted_evidence_types?: [
    "forecast"
    | "measured"
    | "seller_declared",
    ...("forecast" | "measured" | "seller_declared")[],
]

Min Items
1
Optionalaccepted_providers?: [BrandKey, ...BrandKey[]]

Min Items
1
Optionalexcluded_providers?: [BrandKey, ...BrandKey[]]

Min Items
1
Optionalaccepted_subject_types?: [AudienceSubjectType, ...AudienceSubjectType[]]

Min Items
1
Optionalaccepted_resolution_methods?: [AudienceResolutionMethod, ...AudienceResolutionMethod[]]

Min Items
1
Optionalminimum_confidence?: number
Optionalmaximum_age?: Duration & { unit?: "seconds" | "minutes" | "hours" | "days" }
Optionalmethodology_documentation_required?: boolean
Optionalindependent_attestation_required?: boolean
Optionalaccepted_attestation_issuers?: [
    | { type: "brand"; brand: BrandKey; ext?: ExtensionObject }
    | { type: "agent"; agent_url: string; ext?: ExtensionObject }
    | { type: "origin"; origin: string; ext?: ExtensionObject },
    ...(
        | { type: "brand"; brand: BrandKey; ext?: ExtensionObject }
        | { type: "agent"; agent_url: string; ext?: ExtensionObject }
        | { type: "origin"; origin: string; ext?: ExtensionObject }
    )[],
]

Min Items
1
Optionalaccepted_attestation_claim_types?: [string, ...string[]]

Min Items
1
Optionalext?: ExtensionObject

`Optional`audience_evidence_pins

audience_evidence_pins?: [AudienceEvidencePin, ...AudienceEvidencePin[]]

`Optional`agency_estimate_number

agency_estimate_number?: string

`Optional`context

context?: ContextObject

`Optional`ext

ext?: ExtensionObject

`Optional`measurement_terms

measurement_terms?: ProductPurchaseMeasurementTerms

`Optional`performance_standards

performance_standards?: [
CanonicalPerformanceStandard,
...CanonicalPerformanceStandard[],
]

Interface ProposalPurchase

Index

Properties

Properties

product_id

pricing_option_id

Optionalpricing

Optionalformat_option_refs

Optionalcatalog_ids

Optionalbudget

Optionaldaily_budget_cap

Optionalmin_spend_target

Optionalimpressions

Optionalstart_time

Optionalend_time

Optionalpacing

Optionalbidding

Type Declaration

Optionalautomatic?: true

Optionalbid_amount?: number

Optionalmax_bid?: number

Optionalcost_per?: { amount: number; strength: "cap" | "target" }

amount: number

strength: "cap" | "target"

Optionalroas?: { value: number; strength: "target" | "floor" }

value: number

strength: "target" | "floor"

Optionaltargeting_overlay

Optionaloptimization_goals

Optionalaudience_evidence_requirements

Type Declaration

requirement_mode: "required" | "preferred"

evidence_presence: "required" | "when_available"

Optionalaccepted_methodologies?: [AudienceEvidenceMethodology, ...AudienceEvidenceMethodology[]]

Min Items

Optionalexcluded_methodologies?: [AudienceEvidenceMethodology, ...AudienceEvidenceMethodology[]]

Min Items

Optionalaccepted_evidence_types?: [ "forecast" | "measured" | "seller_declared", ...("forecast" | "measured" | "seller_declared")[],]

Min Items

Optionalaccepted_providers?: [BrandKey, ...BrandKey[]]

Min Items

Optionalexcluded_providers?: [BrandKey, ...BrandKey[]]

Min Items

Optionalaccepted_subject_types?: [AudienceSubjectType, ...AudienceSubjectType[]]

Min Items

Optionalaccepted_resolution_methods?: [AudienceResolutionMethod, ...AudienceResolutionMethod[]]

Min Items

Optionalminimum_confidence?: number

Optionalmaximum_age?: Duration & { unit?: "seconds" | "minutes" | "hours" | "days" }

Optionalmethodology_documentation_required?: boolean

Optionalindependent_attestation_required?: boolean

Min Items

Optionalaccepted_attestation_claim_types?: [string, ...string[]]

Min Items

Optionalext?: ExtensionObject

Optionalaudience_evidence_pins

Optionalagency_estimate_number

Optionalcontext

Optionalext

Optionalmeasurement_terms

Optionalperformance_standards

Settings

On This Page

`Optional`pricing

`Optional`format_option_refs

`Optional`catalog_ids

`Optional`budget

`Optional`daily_budget_cap

`Optional`min_spend_target

`Optional`impressions

`Optional`start_time

`Optional`end_time

`Optional`pacing

`Optional`bidding

`Optional`automatic?: true

`Optional`bid_amount?: number

`Optional`max_bid?: number

`Optional`cost_per?: { amount: number; strength: "cap" | "target" }

`Optional`roas?: { value: number; strength: "target" | "floor" }

`Optional`targeting_overlay

`Optional`optimization_goals

`Optional`audience_evidence_requirements

`Optional`accepted_methodologies?: [AudienceEvidenceMethodology, ...AudienceEvidenceMethodology[]]

`Optional`excluded_methodologies?: [AudienceEvidenceMethodology, ...AudienceEvidenceMethodology[]]

`Optional`accepted_evidence_types?: [
"forecast"
| "measured"
| "seller_declared",
...("forecast" | "measured" | "seller_declared")[],
]

`Optional`accepted_providers?: [BrandKey, ...BrandKey[]]

`Optional`excluded_providers?: [BrandKey, ...BrandKey[]]

`Optional`accepted_subject_types?: [AudienceSubjectType, ...AudienceSubjectType[]]

`Optional`accepted_resolution_methods?: [AudienceResolutionMethod, ...AudienceResolutionMethod[]]

`Optional`minimum_confidence?: number

`Optional`maximum_age?: Duration & { unit?: "seconds" | "minutes" | "hours" | "days" }

`Optional`methodology_documentation_required?: boolean

`Optional`independent_attestation_required?: boolean

`Optional`accepted_attestation_claim_types?: [string, ...string[]]

`Optional`ext?: ExtensionObject

`Optional`audience_evidence_pins

`Optional`agency_estimate_number

`Optional`context

`Optional`ext

`Optional`measurement_terms

`Optional`performance_standards