Selling patterns
Everything sellers actually sell composes from the same few objects: packages, pools, rate entries, avails. Every pattern below is a package definition; how the objects fit together is the object model, and the full field reference is the package object. All examples use the sandbox seller acme. The examples are fragments, not full requests: each shows only the objects the pattern turns on. Package and pool objects publish inside the usual PUT /v1/me/catalog envelope (taxonomy_version plus packages[] and pools[]), and rate entries inside a PUT /v1/me/rate-cards commit, exactly as in Publish your catalog; comments mark anything else a real request still needs.
Dayparts and holiday variants
The workhorse: a selling title on a weekly pattern. Seasonal and holiday schedules are not special cases; they are date-bounded versions of the same package.
{ "package_id": "acme-prime", "type": "daypart", "network": "ACME",
"definition": { "selling_title": "Prime", "days": ["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],
"start": "20:00", "end": "23:00" },
"effective": { "start": "2026-09-28", "end": "2026-11-22" } }
// the holiday variant takes over when the first version's window ends
{ "package_id": "acme-prime-holiday", "type": "daypart", "network": "ACME",
"definition": { "selling_title": "Holiday Prime", "days": ["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],
"start": "19:00", "end": "23:00" },
"effective": { "start": "2026-11-23", "end": "2026-12-27" } }
Sports: season, team, game
Games air on dates, not weekly patterns, so a sports program defines itself by occurrences. The season is the package; each game is the slot on its date; a buyer books the season by week or pins a single game by slot.
{ "package_id": "acme-aces-baseball", "type": "program", "network": "ACME",
"definition": { "selling_title": "Aces Baseball", "timezone": "America/Chicago",
"occurrences": [
{ "date": "2027-04-09", "start": "18:30", "end": "22:00", "label": "home opener" },
{ "date": "2027-04-12", "start": "19:00", "end": "22:30", "label": "at Rivertown" } ] } }
// book one game: the line item pins the slot, daylocked by construction
{ "package_id": "acme-aces-baseball", "slot_id": "acme-aces-baseball:2027-04-09",
"units": 2, "spot_length": 30 } // plus provider, network, and rate, as on any catalog order line
Team splits and pre/in/post-game cuts are sibling packages over the same breaks; give them a shared pool (next pattern) and each sells its own cap of the same inventory.
Tentpoles and events
Tentpoles are programs. A premiere, finale, or awards night is an occurrences program with premium weekly rates; cards price by week, so the event week simply carries event pricing.
{ "package_id": "acme-awards-night", "type": "program", "network": "ACME",
"definition": { "selling_title": "Awards Night", "timezone": "America/New_York",
"occurrences": [ { "date": "2027-02-28", "start": "20:00", "end": "23:30" } ] } }
// the event week's rate entry does the premium work
PUT /v1/me/rate-cards
{ "commit": "acme-2027q1-v2", "currency": "USD",
"effective": { "start": "2027-01-04", "end": "2027-03-28" },
"entries": [
{ "package_id": "acme-awards-night", "week": "2027-W09", "class": "scatter",
"advertiser_class": "general", "spot_length": 30, "guarantee_tier": "guaranteed",
"clearance_tier": "P1", "gross_rate_unit": 12500.00 } ] }
Overlapping packages with caps
Selling the same breaks through two packages, each entitled to only so much, is a shared pool. Declare the pool, opt both packages in with their caps, and the catalog integrity rule allows the overlap while the pool enforces the math.
{ "pools": [ { "pool_id": "acme-prime-breaks", "network": "ACME", "unit": "spots",
"capacity": { "grain": "week", "per_week": 80 },
"effective": { "start": "2026-09-28", "end": "2026-12-27" } } ],
"packages": [
{ "package_id": "acme-prime", "type": "daypart",
"definition": { "selling_title": "Prime", "days": ["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],
"start": "20:00", "end": "23:00" },
"inventory_pool": { "pool_id": "acme-prime-breaks", "max_per_week": 60 } },
{ "package_id": "acme-sports-prime", "type": "daypart",
"definition": { "selling_title": "Sports Prime", "days": ["Sat","Sun"], "start": "20:00", "end": "23:00" },
"inventory_pool": { "pool_id": "acme-prime-breaks", "max_per_week": 30 } } ] }
Avails on each package report the smaller of its own remaining cap and the pool's remaining capacity. An order past either limit rejects with INVENTORY_UNAVAILABLE and details.pool_id.
Sponsorships and billboards
News, weather, and segment sponsorships are custom packages with short lengths. Paired open/close billboards use the mirror pattern; buyers opt in per line with include_mirror.
{ "package_id": "acme-wx-sponsor", "type": "custom", "network": "ACME",
"definition": { "selling_title": "Weather Sponsorship", "days": ["Mon","Tue","Wed","Thu","Fri"],
"start": "06:15", "end": "06:20", "mirror": { "offset_minutes": 660 } },
"spot_lengths": [5, 10] }
Rotators, ROS, RON
Rotation rules across windows, or the whole network. ROS and rotator selling titles must carry sample_programming so buyers see representative titles.
{ "package_id": "acme-weekend-rot", "type": "rotator", "network": "ACME",
"definition": { "selling_title": "Weekend Rotator",
"windows": [ { "days": ["Sat","Sun"], "start": "09:00", "end": "20:00" } ],
"sample_programming": ["Gameday Live", "Prime Movie", "Late Slate"] } }
DR and paid programming
Direct response is an advertiser_class with its own rates on any package. Paid programming and shopping blocks are long-form spot_lengths on a custom package.
{ "package_id": "acme-overnight-block", "type": "custom", "network": "ACME",
"definition": { "selling_title": "Overnight Block", "days": ["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],
"start": "02:00", "end": "05:00" },
"spot_lengths": [1800, 3600], "advertiser_classes": ["dr", "paid_programming"] }
Political windows
Political is a rate class, not a package type: political_candidate_lur and political_issue advertiser classes overlay any compatible package, with LUR governing candidate rates. See Political and LUR.
Local stations and station groups
A station is its own network; the group is the provider; geography rides the package's market block, and buyers filter by it. A group-wide buy is one order with one line per station.
{ "package_id": "kacm-early-news", "type": "daypart", "network": "KACM", "provider": "Acme Station Group",
"definition": { "selling_title": "Early News", "days": ["Mon","Tue","Wed","Thu","Fri"],
"start": "17:00", "end": "18:00" },
"market": { "scheme": "nielsen_dma", "code": "501", "name": "New York", "country": "US" } }
// buyers plan by market
GET /v1/sellers/acme-stations/catalog?market=nielsen_dma:501
Selling in another currency
Trade currency is declared per rate-card commit, ISO 4217, and locked with the order. Measurement rides the same open fields with honest source tags, so a Mexican broadcaster sells in MXN against local measurement without any special casing.
PUT /v1/me/rate-cards
{ "commit": "acme-mx-2026q4-v1", "currency": "MXN",
"effective": { "start": "2026-09-28", "end": "2026-12-27" },
"entries": [ { "package_id": "acme-mx-prime", "week": "2026-W41", "class": "scatter",
"advertiser_class": "general", "spot_length": 30, "guarantee_tier": "ng_preemptible",
"clearance_tier": "P2", "gross_rate_unit": 7200.00 } ] }
Remnant and opportunistic windows
Unsold inventory near air publishes as remnant or opportunistic rate entries with a window and a signal, on a standing cadence. Buyers' agents watch for the windows; see Buy remnant and opportunistic inventory.