Skip to content

Add auction pricing for all pricing models #269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
EmmaLouise2018 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add auction pricing for all pricing models #269

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d707ac6
Add auction pricing for all pricing models
EmmaLouise2018 Dec 4, 2025
69f5468
Refactor: Consolidate pricing schemas into single discriminated union
EmmaLouise2018 Dec 9, 2025
5505d41
Refactor: One schema per pricing model with fixed+auction support
EmmaLouise2018 Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .changeset/auction-all-pricing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
"adcontextprotocol": minor
---

Add auction pricing for all pricing models

Previously only CPM and vCPM supported both fixed and auction pricing. Now all pricing models support both variants:
- CPM, vCPM (already supported)
- CPC (Cost Per Click)
- CPCV (Cost Per Completed View)
- CPV (Cost Per View)
- CPP (Cost Per Point)
- Flat Rate

**Schema Architecture:**
Each pricing model has its own schema file that supports both fixed and auction variants using a discriminated union:
- `is_fixed: true` → uses `rate` field for fixed pricing
- `is_fixed: false` → uses `price_guidance` field for auction pricing

**7 pricing model schemas:**
- cpm-option.json
- vcpm-option.json
- cpc-option.json
- cpcv-option.json
- cpv-option.json
- cpp-option.json
- flat-rate-option.json

**TypeScript type safety:**
Uses proper discriminated union with `is_fixed` as the discriminator, enabling TypeScript to narrow types correctly:
- `if (opt.is_fixed) { opt.rate... }`
- `else { opt.price_guidance... }`
116 changes: 108 additions & 8 deletions docs/media-buy/advanced-topics/pricing-models.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ By accepting the product, buyers agree to use the declared measurement provider

**Use Cases**: Video campaigns, audio ads, pre-roll video

**Example**:
**Fixed Example**:
```json
{
"pricing_option_id": "cpcv_usd_guaranteed",
Expand All @@ -129,6 +129,21 @@ By accepting the product, buyers agree to use the declared measurement provider
}
```

**Auction Example**:
Copy link
Contributor

@bokelley bokelley Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

possibly use the testable code to make these maintainable?

Copy link
Contributor Author

@EmmaLouise2018 EmmaLouise2018 Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good suggestion! For pricing-models.mdx, the JSON examples are schema documentation rather than API calls, so testable: true isn't directly applicable here (those tests validate executable code against the test agent API).

However, the schema validation tests do indirectly validate these structures since they test the pricing option schemas. The examples in the doc should match the schema definitions.

If we want explicit validation of doc examples, we could add a test that extracts JSON from the mdx and validates against schemas - happy to add that if useful.

```json
{
"pricing_option_id": "cpcv_usd_auction",
"pricing_model": "cpcv",
"currency": "USD",
"is_fixed": false,
"price_guidance": {
"floor": 0.08,
"p50": 0.12,
"p75": 0.15
}
}
```

**Billing**: Charged only when viewer completes 100% of the video/audio ad. Completion is measured by the declared measurement provider.

---
Expand All @@ -138,9 +153,10 @@ By accepting the product, buyers agree to use the declared measurement provider

**Use Cases**: Video campaigns with shorter completion requirements

**Example**:
**Fixed Example**:
```json
{
"pricing_option_id": "cpv_usd_50pct",
"pricing_model": "cpv",
"rate": 0.08,
"currency": "USD",
Expand All @@ -151,6 +167,24 @@ By accepting the product, buyers agree to use the declared measurement provider
}
```

**Auction Example**:
```json
{
"pricing_option_id": "cpv_usd_50pct_auction",
"pricing_model": "cpv",
"currency": "USD",
"is_fixed": false,
"price_guidance": {
"floor": 0.04,
"p50": 0.07,
"p75": 0.10
},
"parameters": {
"view_threshold": 0.5
}
}
```

**Billing**: Charged when viewer reaches threshold (e.g., 50% completion, 30 seconds)

**Parameters**:
Expand All @@ -163,9 +197,10 @@ By accepting the product, buyers agree to use the declared measurement provider

**Use Cases**: Connected TV, linear TV, radio, audio streaming

**Example**:
**Fixed Example**:
```json
{
"pricing_option_id": "cpp_usd_a18-49",
"pricing_model": "cpp",
"rate": 250.00,
"currency": "USD",
Expand All @@ -178,6 +213,25 @@ By accepting the product, buyers agree to use the declared measurement provider
}
```

**Auction Example**:
```json
{
"pricing_option_id": "cpp_usd_a18-49_auction",
"pricing_model": "cpp",
"currency": "USD",
"is_fixed": false,
"price_guidance": {
"floor": 150.00,
"p50": 225.00,
"p75": 275.00
},
"parameters": {
"demographic": "A18-49",
"min_points": 50
}
}
```

**Billing**: Charged per rating point delivered to target demographic

**Parameters**:
Expand Down Expand Up @@ -219,12 +273,23 @@ Buyers should verify the measurement provider meets their campaign requirements

**Use Cases**: Direct response campaigns, search ads, social advertising

**Example**:
**Fixed Example**:
```json
{
"pricing_option_id": "cpc_usd_fixed",
"pricing_model": "cpc",
"rate": 1.50,
"currency": "USD",
"is_fixed": true
}
```

**Auction Example**:
```json
{
"pricing_option_id": "cpc_usd_auction",
"pricing_model": "cpc",
"currency": "USD",
"is_fixed": false,
"price_guidance": {
"floor": 0.50,
Expand All @@ -243,17 +308,33 @@ Buyers should verify the measurement provider meets their campaign requirements

**Use Cases**: Sponsorships, takeovers, exclusive placements, branded content

**Example**:
**Fixed Example**:
```json
{
"pricing_option_id": "flat_rate_usd_takeover",
"pricing_model": "flat_rate",
"rate": 50000.00,
"currency": "USD",
"is_fixed": true
}
```

**Billing**: Fixed cost for the entire campaign period
**Auction Example**:
```json
{
"pricing_option_id": "flat_rate_usd_takeover_auction",
"pricing_model": "flat_rate",
"currency": "USD",
"is_fixed": false,
"price_guidance": {
"floor": 35000.00,
"p50": 45000.00,
"p75": 55000.00
}
}
```

**Billing**: Fixed cost for the entire campaign period (fixed) or auction-determined price for the placement (auction)

---

Expand Down Expand Up @@ -335,6 +416,8 @@ Publishers can offer the same product in multiple currencies:

## Fixed vs. Auction Pricing

**All pricing models** (CPM, vCPM, CPC, CPCV, CPV, CPP, and Flat Rate) support both fixed and auction pricing variants.

### Fixed Pricing (`is_fixed: true`)
- Publisher sets a fixed rate
- Rate is guaranteed and predictable
Expand All @@ -344,10 +427,27 @@ Publishers can offer the same product in multiple currencies:
### Auction Pricing (`is_fixed: false`)
- Final price determined through auction
- Publisher provides `price_guidance` with floor and percentiles
- Common for non-guaranteed inventory
- Common for non-guaranteed/programmatic inventory
- Buyer submits `bid_price` in media buy request

**Auction Example**:
**Auction CPM Example**:
```json
{
"pricing_option_id": "cpm_usd_auction",
"pricing_model": "cpm",
"currency": "USD",
"is_fixed": false,
"price_guidance": {
"floor": 8.00,
"p25": 10.00,
"p50": 12.00,
"p75": 15.00,
"p90": 18.00
}
}
```

**Auction CPCV Example**:
```json
{
"pricing_option_id": "cpcv_usd_auction",
Expand Down
12 changes: 3 additions & 9 deletions static/schemas/source/core/pricing-option.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,13 @@
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "/schemas/core/pricing-option.json",
"title": "Pricing Option",
"description": "A pricing model option offered by a publisher for a product. Each pricing model has its own schema with model-specific requirements.",
"description": "A pricing model option offered by a publisher for a product. Each pricing model supports both fixed rate (is_fixed: true, rate field) and auction-based (is_fixed: false, price_guidance field) pricing.",
"oneOf": [
{
"$ref": "/schemas/pricing-options/cpm-fixed-option.json"
"$ref": "/schemas/pricing-options/cpm-option.json"
},
{
"$ref": "/schemas/pricing-options/cpm-auction-option.json"
},
{
"$ref": "/schemas/pricing-options/vcpm-fixed-option.json"
},
{
"$ref": "/schemas/pricing-options/vcpm-auction-option.json"
"$ref": "/schemas/pricing-options/vcpm-option.json"
},
{
"$ref": "/schemas/pricing-options/cpc-option.json"
Expand Down
74 changes: 33 additions & 41 deletions static/schemas/source/index.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,47 +356,6 @@
}
}
},
"pricing-options": {
"description": "Individual pricing model schemas with model-specific validation. CPM and vCPM support both fixed and auction pricing; all other models are fixed-rate only.",
"schemas": {
"cpm-fixed-option": {
"$ref": "/schemas/pricing-options/cpm-fixed-option.json",
"description": "Cost Per Mille (CPM) fixed-rate pricing for direct/guaranteed deals"
},
"cpm-auction-option": {
"$ref": "/schemas/pricing-options/cpm-auction-option.json",
"description": "Cost Per Mille (CPM) auction-based pricing for programmatic/non-guaranteed inventory"
},
"vcpm-fixed-option": {
"$ref": "/schemas/pricing-options/vcpm-fixed-option.json",
"description": "Viewable Cost Per Mille (vCPM) fixed-rate pricing for viewability-guaranteed deals"
},
"vcpm-auction-option": {
"$ref": "/schemas/pricing-options/vcpm-auction-option.json",
"description": "Viewable Cost Per Mille (vCPM) auction-based pricing for programmatic inventory with viewability guarantee"
},
"cpc-option": {
"$ref": "/schemas/pricing-options/cpc-option.json",
"description": "Cost Per Click (CPC) fixed-rate pricing for performance campaigns"
},
"cpcv-option": {
"$ref": "/schemas/pricing-options/cpcv-option.json",
"description": "Cost Per Completed View (CPCV) fixed-rate pricing for video/audio"
},
"cpv-option": {
"$ref": "/schemas/pricing-options/cpv-option.json",
"description": "Cost Per View (CPV) fixed-rate pricing with threshold"
},
"cpp-option": {
"$ref": "/schemas/pricing-options/cpp-option.json",
"description": "Cost Per Point (CPP) fixed-rate pricing for TV/audio with demographic measurement"
},
"flat-rate-option": {
"$ref": "/schemas/pricing-options/flat-rate-option.json",
"description": "Flat rate pricing for DOOH and sponsorships"
}
}
},
"media-buy": {
"description": "Media buy task request/response schemas",
"supporting-schemas": {
Expand Down Expand Up @@ -562,6 +521,39 @@
}
}
},
"pricing-options": {
"description": "Individual pricing model schemas with model-specific validation. All pricing models support both fixed rate and auction-based pricing.",
"schemas": {
"cpm-option": {
"$ref": "/schemas/pricing-options/cpm-option.json",
"description": "Cost Per Mille (CPM) pricing - supports both fixed and auction-based pricing"
},
"vcpm-option": {
"$ref": "/schemas/pricing-options/vcpm-option.json",
"description": "Viewable Cost Per Mille (vCPM) pricing - supports both fixed and auction-based pricing"
},
"cpc-option": {
"$ref": "/schemas/pricing-options/cpc-option.json",
"description": "Cost Per Click (CPC) pricing - supports both fixed and auction-based pricing"
},
"cpcv-option": {
"$ref": "/schemas/pricing-options/cpcv-option.json",
"description": "Cost Per Completed View (CPCV) pricing - supports both fixed and auction-based pricing"
},
"cpv-option": {
"$ref": "/schemas/pricing-options/cpv-option.json",
"description": "Cost Per View (CPV) pricing with threshold - supports both fixed and auction-based pricing"
},
"cpp-option": {
"$ref": "/schemas/pricing-options/cpp-option.json",
"description": "Cost Per Point (CPP) pricing for TV/audio - supports both fixed and auction-based pricing"
},
"flat-rate-option": {
"$ref": "/schemas/pricing-options/flat-rate-option.json",
"description": "Flat rate pricing for DOOH and sponsorships - supports both fixed and auction-based pricing"
}
}
},
"adagents": {
"description": "Authorized sales agents file format specification",
"$ref": "/schemas/adagents.json",
Expand Down
Loading