Objects reference

The shapes that recur across the API, each with its full field reference. This page is the canonical definition of every object; endpoint pages link here instead of redefining shapes. How the objects relate: the object model.

package

The sellable unit: seller-defined, versioned, date-bounded. Concept: Packages.

{
  "package_id": "acme-prime",
  "type": "daypart",
  "network": "ACME",
  "provider": "National ACME",
  "definition": {
    "selling_title": "Prime",
    "days": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    "start": "20:00",
    "end": "23:00",
    "timezone": "America/New_York",
    "sample_programming": ["Acme Tonight", "Prime Movie"],
    "mirror": {
      "offset_minutes": 240
    }
  },
  "taxonomy_version": "acme-2026q4-v1",
  "effective": {
    "start": "2026-09-28",
    "end": "2026-12-27"
  },
  "currencies": ["spots", "hh", "p2plus", "a25_54"],
  "buy_types": ["preemptible", "non_preemptible", "fixed_position", "audience_guaranteed"],
  "spot_lengths": [15, 30, 60],
  "advertiser_classes": ["general", "dr", "tune_in", "competitive", "theatrical"],
  "sm_daypart": "Primetime",
  "disclosure": {
    "avails_policy": "published",
    "pricing_policy": "published"
  },
  "market": {
    "scheme": "nielsen_dma",
    "code": "501",
    "name": "New York",
    "country": "US"
  },
  "inventory_pool": {
    "pool_id": "acme-prime-breaks",
    "max_per_week": 60
  },
  "distribution": "network",
  "separation_policy": {
    "min_separation_seconds": 900,
    "scope": "break"
  },
  "posting_policy": {
    "aggregation_weeks": 4,
    "threshold_pct": 90
  }
}

Field	Type	Description
package_id required	string	Stable identifier. Maps to the EDI product code on delivered orders.
type required	enum	One of the package types. Tentpoles are programs.
network required	string	The channel.
provider required	string	The bookable entity. Multi-network sellers carry both: provider books, network airs.
definition required	object	What the package covers. Shape varies by type; fields below.
taxonomy_version required	string	Selling-title definitions are versioned data with effective windows, never enums. Orders pin the version they bought against.
effective.start, effective.end required	ISO date	The package's active window. Holiday variants are just versions.
currencies required	array of string	What the package trades in: spots or audience codes.
buy_types required	array of string	Offered buy types.
spot_lengths	array of integer	Supported creative lengths in seconds.
advertiser_classes	array of string	Accepted advertiser classes. Seller-defined; open.
sm_daypart	string	Mapping to the platform's fixed reporting dayparts. Reporting only; never a booking key.
disclosure	object	How much the package reveals: avails_policy (one of the avails policies) and pricing_policy (one of the pricing policies). Both default to published; overridable per agreement. See Disclosure.
market	object	Geography. Omitted means national. Fields below.
inventory_pool	object	Opts the package into shared capacity: pool_id references a declared pool; max_per_week caps this package's draw. See shared pools.
distribution	enum	The layer the inventory sits in: one of the distributions. Omitted means unstated. Independent of market: spot with no market is national spot, spot with a market is local. See Distribution.
separation_policy	object	The seller's stated competitive-separation rule: min_separation_seconds and a scope of break, pod, or program. Recorded and surfaced, not scheduled around: advertiser_class prices, advertiser_category separates. See Competitive separation.
posting_policy	object	When an audience shortfall owes a make-good; fields below. Overridable per agreement. Evaluated per line, never order-wide. See Posting policy.
billboard	object	Only on type: "sponsorship": seconds (typically 3, 5, or 10) and position (open, close, or both). A billboard is a benefit attached to a schedule, not a spot with a short spot_length. See Sponsorships and billboards.

posting_policy

Field	Type	Description
aggregation_weeks required	integer	The window delivery totals over before shortfall is computed. Four is the industry-recommended figure; the field carries whatever the parties agreed.
threshold_pct required	number	Delivery at or above this percentage of the guarantee owes no make-good. Inclusive at the edge.
exclusions	array of string	package_id references the policy does not cover: the tentpole carve-out, where one event's delivery is negotiated on its own.

definition

Field	Type	Description
selling_title	string	Daypart packages: the seller's own selling title, with days, start, and end. Program and genre packages carry program or genre references instead; rotators carry rotation rules.
days	array of string	Weekday pattern, Mon through Sun.
start, end	string	Local time range, HH:MM, resolved against timezone at ingest.
occurrences	array of object	Event-dated programs replace days/start/end with dated occurrences: {date, start, end, label}. Slots then exist only on those dates.
timezone required	string	IANA timezone the local times resolve against.
sample_programming	array of string	Representative programming. Required on ROS and RON selling titles.
mirror.offset_minutes	integer	Paired mirror airing at a fixed offset: the "8P-12A with 12A-4A mirror" pattern. Order lines opt in with include_mirror.

market

Field	Type	Description
scheme required	enum	One of the market schemes.
code required	string	The market code within the scheme, for example DMA 501.
name	string	Display name.
country	string	ISO country code.

pool

Seller-owned shared capacity. Packages that declare the same inventory_pool may overlap in coverage (the declared exception to the catalog integrity rule) and draw down one capacity, each bounded by its own max_per_week. Concept: Packages: shared 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"
  }
}

Field	Type	Description
pool_id required	string	Referenced by package.inventory_pool.pool_id. Validated at ingest: the pool must exist on the same seller and network, with matching unit and a covering effective window, or the catalog update rejects.
network required	string	Pools do not span networks.
unit required	string	What the capacity counts, for example spots.
capacity.grain, capacity.per_week required	object	The shared floor. Member caps may add up to more than the pool; the pool holds either way, first committed wins.
effective.start, effective.end required	ISO date	Must cover the coverage of every member package.

slot

A package on a date: the orderable instance. Slots are not a registry; the ID is derived, and a slot inherits the rate entries of its ISO week. The grain rule in one sentence: cards price by week; trades book by slot. Concept: Packages: slots.

{
  "slot_id": "acme-prime:2026-10-07",
  "package_id": "acme-prime",
  "date": "2026-10-07",
  "week": "2026-W41"
}

Field	Type	Description
slot_id required	string	Always {package_id}:{date}. Constructible; no lookup needed.
package_id required	string	The package this slot instantiates.
date required	ISO date	Booking a slot pins this air date: daylocked by construction.
week required	ISO week	The date's ISO week; the rate entries it inherits.

rate entry

One priced cell of a rate card commit: (package, week) by advertiser class, length, buy type, clearance tier, and market class. Concept: Rates.

{
  "package_id": "acme-prime",
  "week": "2026-W41",
  "advertiser_class": "general",
  "spot_length": 30,
  "buy_type": "preemptible",
  "clearance_tier": "P2",
  "class": "scatter",
  "rate_basis": "per_unit",
  "gross_rate_unit": 405.00,
  "gross_rate_weekly": 4050.00,
  "currency": "USD",
  "locked_rate_id": "lr_88c1",
  "commit": "acme-2026q4-v2",
  "commit_kind": "standing",
  "agreement_scope": null
}

Field	Type	Description
package_id, week required	string, ISO week	Cards price by week; the week's slots inherit these entries.
advertiser_class required	enum	One of the advertiser classes. Seller-defined; open.
spot_length required	integer	Creative length in seconds this rate prices.
buy_type required	enum	One of the buy types.
clearance_tier	enum	One of the clearance tiers; permitted only for preemptible.
class required	enum	Market timing, one of the market classes. Political LUR is an advertiser class, not a market class; negotiated pricing is agreement-scoped, not a class.
rate_basis required	enum	One of the rate bases; names the authoritative cost field.
gross_rate_unit, gross_rate_cpm	number	Exactly the field selected by rate_basis is required. An audience_guaranteed entry prices per_unit like any spot-cost buy type: gross_rate_unit is the fixed price of one guaranteed unit. cpm remains a rate basis of its own, priced by gross_rate_cpm, for a buy type that settles on an uncapped, buyer-named impression count rather than a fixed unit. Each creative length a card prices is its own entry with its own price: no rate is ever derived from another length's.
gross_rate_weekly	number	Optional weekly rollup, honestly named.
guaranteed_impressions	integer	Required on audience_guaranteed only: the impressions this audience guarantees per unit bought, informational to pricing. A line's total guarantee is guaranteed_impressions x units.
audience_code	string	Required on audience_guaranteed, and on any entry pricing cpm; one of the audience codes.
currency required	ISO 4217	Declared once per card commit and echoed per entry. One trade currency per commit and per order: locked at order time, carried, never converted.
locked_rate_id required	string	What an order line cites to lock this price. See the price-clearance invariant.
commit required	string	The versioned card commit this entry belongs to.
commit_kind	enum	standing (default) or quote. A quote commit is minted per campaign inside a plan, or by a seller's counter at the review gate. It carries quote_expires_at, plus a proposal_ref when a plan minted it or the order and unit it answers when a counter did, and locks like any card on confirm. See Disclosure.
quote_expires_at	ISO datetime	Set on quote commits: after it, the entry is a stale card and returns STALE_RATE_CARD.
agreement_scope	string	null on open cards; an agreement id on buyer-scoped cards and quotes minted for one buyer alone.

avail

One availability statement at the seller's declared precision. A week-grain entry speaks for every slot in that week; a date-grain entry speaks for one slot. The platform never invents per-date data from a week-grain statement. Concept: Currencies.

{
  "package_id": "acme-prime",
  "week": "2026-W41",
  "grain": "week",
  "date": null,
  "slot_id": null,
  "state": "available",
  "basis": "actual",
  "spots": {
    "available": 42,
    "total": 80
  },
  "impressions": {
    "hh": {
      "per_spot": 128000,
      "source": "nielsen",
      "stream": "c3"
    }
  },
  "sellout_level": 0.62,
  "as_of": "2026-10-01T12:00:00Z"
}

Field	Type	Description
package_id, week required	string, ISO week	What the statement covers.
grain required	enum	week or date: the seller's declared precision.
date, slot_id	ISO date, string	Populated when grain is date; the one slot the entry speaks for.
state required	enum	One of the avail states.
basis required	enum	actual or projected.
spots.available, spots.total	object	Unit counts for spot currency.
impressions	object	Map keyed by audience code; each value carries per_spot, source, and stream (c3, c7, live_sd). The platform carries these figures; it never computes them.
sellout_level	number	0 to 1.
as_of required	ISO datetime	Staleness marker for the two-phase availability pattern.
pool	object	Echoed on pooled packages: {pool_id, remaining}. Pooled avails report the lower of package cap remaining and pool remaining.

order

The transaction. Price locks at order time; later card changes never invalidate an accepted price. Concept: Orders; lifecycle: the state machine.

{
  "order_id": "ord_9f3a12c4b7e1",
  "external_order_id": "q4-campaign-042",
  "buyer_entity": "yourco",
  "seller": "acme",
  "workflow": "catalog",
  "status": "placed",
  "substatus": null,
  "last_seq": 5,
  "rate_version": "acme-2026q4-v1",
  "settlement_mode": "direct",
  "buyer_metadata": { "advertiser": "Northwind Coffee" },
  "issued_at": "2026-09-10T09:00:00Z",
  "flight": { "start": "2026-10-05", "end": "2026-10-11" },
  "revision": { "version": 1, "supersedes": null },
  "line_items": [
    {
      "unit_id": "u-0001",
      "package_id": "acme-prime",
      "provider": "National ACME",
      "network": "ACME",
      "week": "2026-W41",
      "slot_id": null,
      "units": 10,
      "spot_length": 30,
      "rate": {
        "class": "scatter",
        "advertiser_class": "general",
        "buy_type": "preemptible",
        "clearance_tier": "P2",
        "rate_basis": "per_unit",
        "unit_cost": 405.00,
        "locked_rate_id": "lr_88c1",
        "currency": "USD"
      },
      "status": "accepted",
      "num_requested": 10,
      "num_accepted": 10,
      "allocation": [
        {
          "date": "2026-10-05",
          "units": 4
        },
        {
          "date": "2026-10-07",
          "units": 3
        },
        {
          "date": "2026-10-09",
          "units": 3
        }
      ]
    }
  ],
  "totals": {
    "gross": 4050.00,
    "currency": "USD"
  }
}

Field	Type	Description
order_id required	string	Platform-minted, ord_ plus 12 hex.
external_order_id required	string	Your idempotency key, echoed on every event. Byte-identical resubmission replays the stored response; 409 only on a changed payload.
buyer_entity	string	The acting buyer the order was booked under. Server-derived from the credential, never from the request body: a body value that disagrees is refused with 403 TENANT_MISMATCH rather than trusted. Echoed on every read. See acting-buyer identity and the tenant roster.
seller required	string	The counterparty.
workflow	enum	One of the workflows. Default: catalog.
status, substatus	enum	One of the order statuses. Switch on status; step markers stay informational.
last_seq	integer	The latest event sequence, for replay via GET /events.
rate_version required	string	The card commit the order prices against. See the price-clearance invariant.
settlement_mode	enum	One of the settlement modes. Default: direct.
issued_at	string	When the buyer's system issued the order, as distinct from when the platform received it. Present on every order: it defaults to created_at when the create stated none, so a lead-time calculation never has to branch on its absence.
flight	object	The window the order states for itself, {start, end} as ISO dates. Absent when the create stated none. When present, every date the order's lines can land on falls inside it: the create is refused otherwise. See POST /orders.
revision	object	The order's place in its own lineage. version is platform-assigned, 1 on an original. supersedes names the order this one replaced, null on an original. superseded_by appears on an order a revision has replaced, alongside status: "canceled" and cancellation.reason: "superseded_by_revision". See revisions.
line_items required	array of object	One line books one week or one slot. Fields below.
attachments	array of object	Paper the buyer sent alongside the lines, echoed verbatim on both order reads: {upload_id, format, role, filename, sha256} per entry. Never parsed and never a source of any field above; the lines stay authoritative. Absent when the create carried none. See attachments[].
buyer_metadata required	object	advertiser is required at create: an order cannot be placed without naming who the buy is for, because separation, category conflict, and political compliance are all undecidable without it. Other named keys include advertiser_category and estimate_id, the agency estimate number echoed on EDI delivery. Without it, agency billing systems cannot match the record. advertiser_category is an open string naming what the advertiser sells, which is what competitive separation runs on; it is not advertiser_class, which is what prices.
agreement_id	string	The agreement presented at create, echoed so the terms governing the order stay resolvable from the snapshot. Absent when none was presented. This is what a posting policy override resolves against when a post lands.
cancellation_terms	object	Snapshotted by value at create from the presented agreement: {notice_days, notes?}. Absent when the create presented no agreement_id. A later agreement change never alters it, exactly as a locked price. See Cancellation and posting terms.
totals.gross, totals.currency, totals.impressions	object	Gross total in the order's one trade currency, plus impression totals per traded audience.

line_items[]

Field	Type	Description
unit_id	string	Platform-assigned per line; how results and counters reference lines.
package_id required	string	From the seller's catalog.
provider, network required	string	Bookable entity and channel.
week	ISO week	Books a package week; the seller distributes units across the week's slots. Set week or slot_id, not both.
slot_id	string	Books one slot: acme-prime:2026-10-07. Daylocked by construction.
units	integer	Every catalog buy type books in units, audience_guaranteed included: a unit is a fixed-price, seller-published guarantee block, not a buyer-named impression count. Set units or impressions_goal, not both.
impressions_goal	integer	For impression currency (proposal and document workflows; see Proposals). A catalog line never sets this: the seller's own catalog has no cell priced against a buyer-chosen impression count.
spot_length required	integer	Seconds; must be a length the rate entry prices.
include_mirror	boolean	Books the package's paired mirror airing too. Default: false.
rate required	object	{class, advertiser_class, buy_type, clearance_tier?, rate_basis, unit_cost? or cpm?, locked_rate_id, currency}: the priced cell the line locks, citing its rate entry.
rc_impressions	object	Impression estimates at order time, per audience code, kept for buysheet parity.
copy_id	string	Creative reference. Ad-ID and ISCI identifiers ride here; the platform treats it as an opaque string. Optional before placed and required by it, per the create reference.
copy_name	string	A human-readable name for the creative, beside copy_id. Optional, additive, and never a substitute for the code.
status	enum	Result, one of the unit statuses.
num_requested, num_accepted	integer	Partial acceptance reports per unit; order-level partial is a completed order with a mixed unit set, never a stall.
allocation	array of object	Authoritative air dates once decided: {date, units} entries summing to num_accepted. Slot lines have a single entry; week lines may spread across the package's weekday pattern. A multi-unit week line never collapses to one date.
reason	string	Populated on rejected and countered lines; persisted.
in_response_to	string	On countered lines: the unit_id this counter answers. Counters are additive result lines; see Negotiation.

order_event

The append-only record of everything that happens to an order. Delivery semantics: the event envelope.

{
  "order_id": "ord_9f3a12c4b7e1",
  "external_order_id": "q4-campaign-042",
  "buyer_entity": "yourco",
  "seq": 5,
  "status": "placed",
  "substatus": null,
  "units": [
    {
      "unit_id": "u-0001",
      "status": "accepted",
      "num_accepted": 10
    }
  ],
  "artifact": {
    "name": "placement_receipt",
    "seller_order_id": "ACME-77120"
  },
  "error": null,
  "occurred_at": "2026-10-02T14:41:09Z"
}

Field	Type	Description
order_id, external_order_id required	string	Both ids on every event.
event_type required	string	One of the event types, named for the side reading it: the seller_review transition is order.status_changed to the buyer and order.needs_review to the seller. Same event, same seq.
buyer_entity	string	The acting buyer, carried on the envelope so a seller can attribute an event when one connection serves several buyer organisations. Absent on an order booked before the field existed.
seq required	integer	Strictly increasing per order. Retries reuse the seq; dedup on (order_id, seq).
status required	enum	One of the order statuses.
substatus	string	Informational step marker.
units	array of object	Per-unit results when the transition carries them.
artifact	object	Attached document or receipt, by name: placement_receipt (the booking receipt: the seller's order ID and daylocks), parsed buysheets, delivery posts.
copy	array of object	The creative reference per line: {unit_id, copy_id?, copy_name?}. On every order.status_changed event, so a consumer following the stream always knows which spot each line names. Absent when no line names either field. It rides the envelope rather than units because units carries the results of a transition, so it is absent on the earlier ones and omitted from replay entirely.
attachments	array of string	The upload_id list of the order's attachments, on the event that moves the order to seller_review and nowhere else, so a traffic desk knows paper exists before opening the order. That event reaches the seller as order.needs_review and the buyer as order.status_changed. IDs only: the hashes and filenames are on the order. Not an artifact: an artifact is something the platform produced, an attachment is something the buyer sent.
superseded_by	string	On the order.canceled event a revision produces, naming the revision that replaced this order. Absent on every other cancellation, and there is no separate substatus for a supersede: the cancellation reads like any other, and the lineage is here.
error	object	{error_code, stage, recoverable}. Codes are UPPERCASE; see Errors.
occurred_at required	ISO datetime	UTC.

negotiation

The offer and counter history of one order. The order parks in negotiating between rounds. Concept: Negotiation.

{
  "negotiation_id": "neg_33a7",
  "order_id": "ord_9f3a12c4b7e1",
  "state": "countered",
  "rounds": [
    {
      "actor": "seller",
      "counter": {
        "unit_id": "u-0002",
        "week": "2026-W42",
        "unit_cost": 392.00,
        "num_offered": 8
      },
      "expires_at": "2026-09-30T20:00:00Z"
    }
  ]
}

Field	Type	Description
negotiation_id, order_id required	string	One negotiation per order.
state required	enum	One of open, countered, accepted, expired, withdrawn.
rounds required	array of object	Each round: {offer, counter, actor, expires_at}. Counters surface on the order as additive lines with in_response_to.

proposal_request

The buyer's open ask: carried on POST /orders with workflow: "proposal" in the request field instead of line items. No package IDs required. Concept: Proposals.

{
  "request_type": "audience_plan",
  "audience": {
    "definition": {
      "demo": "A25-54",
      "segments": ["auto_intenders_q4"]
    },
    "currency_goal": {
      "unit": "a25_54",
      "target": 42000000
    }
  },
  "anchor_package_ids": ["acme-prime"],
  "budget_gross": 500000,
  "flight": {
    "start": "2026-10-05",
    "end": "2026-12-27"
  },
  "constraints": {
    "spot_lengths": [15, 30],
    "max_unit_cost": 450.00
  },
  "acceptance_band": {
    "metric": "delivery",
    "tolerance_pct": 2,
    "action": "auto_accept"
  },
  "brief": "Reach auto intenders in the Northeast; avoid overnight rotations."
}

Field	Type	Description
request_type required	enum	One of the request types.
audience.definition	object	An inline audience definition. Set one of definition, audience_id, or upload_id.
audience.audience_id	string	A shared audience reference.
audience.upload_id	string	An uploaded plan or audience file.
audience.currency_goal	object	{unit, target}: the audience code and impression goal the plan should hit.
anchor_package_ids	array of string	Optional starting points.
budget_gross required	number	Gross, in the trade currency.
flight.start, flight.end required	ISO date	The flight window.
constraints	object	Spot lengths, max unit cost, copy splits, daypart mix.
acceptance_band	object	Optional auto-accept tolerance: metric (delivery or budget), tolerance_pct (a percentage; 2 means 2%), and action (auto_accept or flag). The platform evaluates it deterministically against the request target when the plan returns; the comparison is one-sided per metric. The exact math, boundary, and missing-metric rules, with worked examples, are on Proposals.
brief	string	Free text for the seller's planners.

The seller's plan_proposal response prices line items off their card and may mint custom packages scoped to your agreement: each gets a real package_id and books through the same rails. Rates it mints per campaign are quote commits. Where the seller cannot meet the whole ask, the plan returns the shortfall as unmet[] rather than a silent gap. Nothing books until you confirm, or until an acceptance_band you set fires.

plan_proposal

The seller's answer to a proposal order: the assembled first-pass plan, attached as an artifact when the order enters needs_confirmation. The seller writes it with POST /me/orders/{id}/plan; the buyer confirms, counters, or declines. Concept: Proposals.

{
  "name": "plan_proposal",
  "plan_id": "plan_5b2e",
  "proposal_ref": "ord_c19a44e2f0b1",
  "line_items": [
    {
      "package_id": "acme-auto-q4-9f",
      "minted": true,
      "week": "2026-W40",
      "impressions_goal": 21000000,
      "spot_length": 30,
      "rate": {
        "class": "scatter",
        "buy_type": "audience_guaranteed",
        "rate_basis": "cpm",
        "cpm": 11.90,
        "locked_rate_id": "lr_q_2f7a",
        "currency": "USD",
        "commit_kind": "quote"
      }
    }
  ],
  "minted_packages": ["acme-auto-q4-9f"],
  "quote_refs": ["acme-yourco-q4-quote-1"],
  "plan_totals": {
    "gross": 499800.00,
    "currency": "USD",
    "projected_delivery": {
      "a25_54": 41800000
    }
  },
  "unmet": [
    {
      "requested": "overnight rotations",
      "reason": "held for a committed buyer"
    }
  ],
  "expires_at": "2026-09-30T20:00:00Z",
  "created_at": "2026-09-23T15:10:00Z"
}

Field	Type	Description
plan_id required	string	The plan's id; referenced when the buyer confirms or counters.
proposal_ref required	string	The order_id of the proposal order this plan answers.
line_items required	array of object	The proposed buy. Same shape as an order line, each citing a locked_rate_id; minted: true marks a package minted for this request.
minted_packages	array of string	The package_ids minted for this request, scoped to your agreement and reorderable next quarter.
quote_refs	array of string	The quote rate-card commits the line rates lock against; each carries a quote_expires_at.
plan_totals required	object	{gross, currency, projected_delivery}. projected_delivery is a map keyed by audience code; it is the figure an acceptance_band with metric: delivery is checked against.
unmet	array of object	The availability counter: what the seller could not fill, each {requested, reason}. Empty when the plan meets the whole ask.
expires_at required	ISO datetime	The plan offer's own validity; after it, the order lapses. Distinct from a quote's quote_expires_at (the rate's validity).
created_at required	ISO datetime	When the seller returned the plan.

delivery_post

Seller-supplied actuals, attached to an order as an artifact. Audience guarantees reconcile against it; the platform carries the numbers and never computes them. Concept: Reconciliation.

{
  "name": "delivery_post",
  "order_id": "ord_9f3a12c4b7e1",
  "week": "2026-W41",
  "units": [
    {
      "unit_id": "u-0001",
      "aired": 10,
      "delivered": {
        "hh": 1260000,
        "p2plus": 1910000,
        "a25_54": 804000
      },
      "source": "nielsen"
    }
  ],
  "currency_of_record": "a25_54",
  "shortfall": null
}

Field	Type	Description
order_id, week required	string, ISO week	Posts are week-grain per-unit counts today.
units required	array of object	Per unit: aired count, delivered impressions keyed by audience code, and source.
currency_of_record required	string	The audience the guarantee settles on.
shortfall	object	Populated when a guarantee under-delivers. Whether it owes a make-good is decided by the line's effective posting_policy; where none is stated, the shortfall is reported and the decision stays with the parties.

capability_profile

What a seller's connection can do. The orchestrator never calls what the profile does not advertise; it degrades gracefully instead. Endpoints: Capabilities. Concept: Connections.

{
  "seller_id": "acme",
  "conformance_level": 2,
  "transports": {
    "result_delivery": ["callback", "poll", "sqs", "console"],
    "formats": ["json", "csv", "xlsx"]
  },
  "capabilities": {
    "realtime_availability": true,
    "counter_proposals": false,
    "reservation_hold": false,
    "pricing_modes": ["rate_card"]
  },
  "rate_management": {
    "mode": "frozen_quarterly"
  },
  "tenant_policy": {
    "mode": "open"
  },
  "sla": {
    "standard": {
      "min_lead_minutes": 2880,
      "max_decision_latency_seconds": 14400
    }
  }
}

Field	Type	Description
seller_id required	string	The tenant the profile describes.
conformance_level required	integer	0 through 4. See Seller levels.
transports.result_delivery required	array of string	Delivery rungs offered: callback, poll, sqs, console.
transports.formats	array of string	File formats accepted and produced.
capabilities.realtime_availability	boolean	Live avails vs declared cadence.
capabilities.counter_proposals	boolean	Level 3 counters on decide.
capabilities.reservation_hold	boolean	Level 4 holds with TTL.
capabilities.pricing_modes	array of string	rate_card, clearance, negotiated.
rate_management.mode	enum	frozen_quarterly, live_avails, or live_rates.
tenant_policy.mode	enum	How you treat an acting buyer you have not allowlisted. open (default): its order reaches seller_review like any other and you decline there. allowlist: it is refused at intake with 403 and no order is created. Either way, suspension refuses regardless. See the tenant roster.
sla	object	Per service class: minimum lead time and maximum decision latency.

tenant_roster_entry

One acting buyer as a seller sees it. A connection can carry several buyer organisations; this is how a seller tells them apart and stops one without disturbing the rest. Endpoints: the tenant roster.

{
  "buyer_entity": "yourco",
  "status": "active",
  "allowlisted": false,
  "first_seen_at": "2026-10-01"
}

Field	Type	Description
buyer_entity required	string	The acting buyer, as it appears on every order from it. An authorization principal, not a database key: it may stand for an agency, an advertiser, or another buyer organisation.
status required	enum	active or suspended. A suspended tenant's POST /v1/orders is refused with 403 and creates nothing.
allowlisted required	boolean	Whether the seller admitted this tenant explicitly. Consulted only under tenant_policy.mode: "allowlist"; see capability_profile.
reason	string	The seller's note from the suspension. Absent on an active tenant.
first_seen_at required	date	When this tenant first appeared on the connection, whether by sending an order or by being allowlisted ahead of one.

agreement

The relationship, made explicit: functionally a deal ID. Presenting it unlocks private catalog scope, buyer-scoped rate cards, permitted buy types, and the settlement mode. Concept: Agreements.

{
  "agreement_id": "agr_71c0d2",
  "buyer": "yourco",
  "seller": "acme",
  "catalog_scope": ["open", "private"],
  "rate_card_refs": ["acme-yourco-2026q4"],
  "permitted_buy_types": ["preemptible", "non_preemptible", "fixed_position", "audience_guaranteed"],
  "settlement_mode": "direct",
  "disclosure_overrides": [
    { "package_id": "acme-prime", "avails_policy": "published", "pricing_policy": "agreement" },
    { "package_id": "*", "avails_policy": "on_request" }
  ],
  "cancellation_terms": {
    "notice_days": 14
  },
  "posting_policy_overrides": [
    { "package_id": "acme-prime", "posting_policy": { "aggregation_weeks": 4, "threshold_pct": 95 } }
  ],
  "credit": null,
  "effective": {
    "start": "2026-10-01",
    "end": "2027-09-30"
  }
}

Field	Type	Description
agreement_id required	string	What rate_entry.agreement_scope and minted proposal packages reference.
buyer, seller required	string	The two parties.
catalog_scope required	array of string	open, private, or both.
rate_card_refs	array of string	Buyer-scoped card commits only this buyer can transact.
permitted_buy_types	array of string	Permitted buy types under this agreement.
settlement_mode required	enum	One of the settlement modes.
disclosure_overrides	array of object	Seller-authored, optional. Each entry is {package_id, avails_policy?, pricing_policy?}, where package_id may be "*" for all packages in scope. For a buyer presenting this agreement, the effective policy per field resolves as override(package_id) ?? override("*") ?? package.disclosure ?? published (avails and pricing independent; an omitted field inherits the package default). This is how a seller publishes to a trusted buyer while withholding from the open catalog. Buyers never set disclosure; an override naming a package outside catalog_scope is a no-op. See Disclosure.
cancellation_terms	object	notice_days (integer) and optional notes. Orders snapshot these by value at create, so a later change to the agreement leaves booked orders alone. See Cancellation and posting terms.
posting_policy_overrides	array of object	Seller-authored, optional. Each entry is {package_id, posting_policy}, where package_id may be "*". The effective policy for a line resolves as override(package_id) ?? override("*") ?? package.posting_policy ?? unstated, the same precedence as disclosure_overrides. See Posting policy.
credit	object	Populated on cleared agreements: limit and exposure. See GET /settlement/credit.
effective.start, effective.end required	ISO date	The agreement's window.

Enumerations

Every enumerated value in the API, defined once. Field tables across the docs link here; lifecycle and business meaning live on the linked concept pages. Enums marked open may grow: treat unknown values as pass-through, never as errors.

package.type

Value	Meaning
daypart	A selling title over a weekday pattern and local time range.
program	A named program; event-dated programs use occurrences. Tentpoles are programs.
genre	A genre reference.
rotator	Rotation rules across dayparts or titles.
ron	Run of network.
sponsorship	All or part of a program bought by one advertiser. Carries an optional billboard block. Not a buy type: it composes with one.
custom	Seller-defined; includes agreement-scoped packages minted from proposals.

Semantics: Packages. Roadblock, piggyback, bookending, and infomercial are deliberately not types: the first is a multi-package booking, the middle two are trafficking arrangements, and an infomercial is a spot_length of 1800 with the dr advertiser class.

distribution

Value	Meaning
network	The national commercial load carried at once across owned-and-operated and affiliated stations.
syndication	Time inside a program licensed for national distribution that airs on individual local stations.
spot	Time sold by an individual station or system.

Optional; omitted means unstated. Geography stays on market, so spot plus a market is local spot and there is no local_spot value. Semantics: Distribution.

buy_type

Value	Meaning
preemptible	Pay for what airs; the seller may preempt.
non_preemptible	The spot airs; the seller chooses placement within the package.
fixed_position	The spot airs in the position bought.
audience_guaranteed	Audience guarantee; shortfalls trigger the make-good policy.

Semantics: Buy types and guarantees.

workflow

Value	Meaning
catalog	Line items against published packages. Default.
document	A document reference; parsed, validated, and confirmed at needs_confirmation.
proposal	An open proposal request; the seller returns a plan.

Semantics: Submit a document order and Proposals.

rate_basis

Value	Meaning
per_unit	gross_rate_unit prices one spot, at the entry's own spot_length.
cpm	gross_rate_cpm prices one thousand impressions.

audience_guaranteed requires per_unit, priced and booked the same way every spot-cost buy type is: a fixed price per unit, with the guaranteed audience stated per unit on the rate entry (guaranteed_impressions) rather than driving the price. cpm is its own rate basis, for the proposal and document workflows' uncapped, buyer-named impression counts (see Proposals); no catalog cell prices on it.

There is no per-second basis. Creative length is a key axis of the rate card, so a card states a price for each length it sells and the platform derives none of them: a :15 is whatever you priced it at, not a fraction of your :30. A length your card does not price has no rate entry and no locked_rate_id, so it cannot be ordered from the catalog; the proposal path is where a buyer asks for one.

class (market timing)

Value	Meaning
scatter	In-quarter buying at card rates.
upfront	Committed money against a future season. See Upfront.
remnant	Discounted unsold inventory, preemptible.
opportunistic	Last-minute clearance windows.

Timing, not geography. Political LUR is an advertiser class; negotiated pricing is agreement-scoped. Semantics: The deal model.

clearance_tier

Value	Meaning
P1	Highest clearance priority; last to be preempted.
P2	Standard priority.
P3	Lowest priority; first to be preempted.

Semantics: Guarantees.

advertiser_class

Value	Meaning
general	General market.
dr	Direct response.
tune_in	Network tune-in and promotional advertisers.
competitive	Category-competitive rates.
theatrical	Studio and entertainment releases.
political_candidate_lur	Candidate buys at lowest unit rate. See Political buying.
political_issue	Issue advertising; LUR does not apply.

Open enum, seller-defined: a seller's card may carry classes beyond these. Semantics: Rates.

avail.state

Value	Meaning
available	Clearable now.
unavailable	Sold out or blocked.
projected	Quotable, not firmly clearable.

Semantics: Avails.

order status

Value	Meaning
draft, submitted, validating	Intake.
needs_confirmation	The buyer confirms an artifact before it books: a document workflow's parsed interpretation, or a proposal's seller-returned plan_proposal.
confirmed	Validated and confirmed.
negotiating	Parked between rounds: the negotiated workflow, or a proposal counter.
seller_review	The seller's approval gate.
placed, completed	Booked; done. Order-level partial is a completed order with a mixed unit set.
rejected, canceled, failed	Terminals.

Semantics: The state machine.

unit status

Value	Meaning
pending	Not yet decided.
accepted	Booked as requested.
rejected	Declined; reason populated.
partial	Fewer units than requested; see num_accepted.
countered	An additive counter line; in_response_to names the unit it answers.

Semantics: Orders.

settlement_mode

Value	Meaning
direct	You invoice each other; the platform carries the paper trail. Default.
cleared	The platform clears the trade. Optional; per agreement.

Semantics: Settlement.

proposal request_type

Value	Meaning
audience_plan	An audience definition and goal in; a priced plan back.
specs	Concrete constraints in; a plan that satisfies them back.
open	A brief; the seller's planners propose.

Semantics: Proposals.

disclosure.avails_policy

Value	Meaning
published	The tri-state avails feed is materialized and queryable. Default.
on_request	No standing feed; a read returns 202 and the seller answers a scoped query.
withheld	Availability is never exposed; a read returns 409 AVAILS_WITHHELD. Resolves at seller review or in a plan.

Semantics: Disclosure.

disclosure.pricing_policy

Value	Meaning
published	An open rate card visible to any authorized buyer. Default.
agreement	A buyer-scoped card, the deal-ID pattern, unlocked by presenting the agreement.
quote	Priced per campaign as a quote commit inside a plan.

Semantics: Disclosure.

market.scheme

Value	Meaning
nielsen_dma	Nielsen DMA codes.
msa	Metropolitan statistical areas.
cable_zone	Cable interconnect zones.
country	National markets outside the US schemes.
custom	Seller-defined geography.

Open enum. Omitting market entirely means national. Semantics: Packages: markets.

audience codes

Value	Meaning
spots	Unit currency: count of airings.
hh	Household impressions.
p2plus	Persons 2+.
a25_54 and other demo codes	Standard demos.
custom:<def>	Seller-declared custom audiences.

Open enum. Semantics: Currencies.