← Back to product·Simulmedia VAMOS Docs·Concepts / Agreements
Concepts

Agreements

An agreement is the relationship, made explicit. It answers what this buyer can see from this seller, at what rates, for which buy types, and how money settles. If you know programmatic, the mental model is a deal ID: presenting it is proof of the relationship, and proof unlocks the terms.

{
  "agreement_id": "agr_71c0d2",
  "buyer": "yourco",
  "seller": "acme",
  "catalog_scope": ["open", "private"],
  "rate_card_refs": ["acme-yourco-2026q4"],
  "permitted_grains": ["week", "month"],
  "permitted_buy_types": ["preemptible", "non_preemptible", "fixed_position", "audience_guaranteed"],
  "settlement_mode": "direct",
  "effective": {
    "start": "2026-10-01",
    "end": "2027-09-30"
  }
}

rate_card_refs names the buyer-scoped cards only you can transact; settlement_mode is direct or cleared; a cleared agreement's live credit position is read at GET /settlement/credit?agreement=, one authoritative surface for a number that can refuse an order, never a copy inside this cacheable object. The field-by-field reference lives at the agreement object.

What an agreement unlocks

Presenting an agreement changes what you can see and do on the marketplace, across five dimensions:

  • Visibility: private catalogs and buyer-scoped rate cards appear only when your agreement carries them; open catalogs need no agreement beyond platform access.
  • Pricing: sellers mint rate cards per agreement, the deal-ID-floor pattern: your negotiated rates, invisible to everyone else, validated under the same price-clearance invariant.
  • Buy types, grains, and workflow: a seller can allow instant book for trusted buyers and request-and-approve for everyone else, and can narrow which buy types and which purchase grains one buyer may book. See what a relationship permits.
  • Settlement: direct vs cleared is an agreement property, echoed on every order.
  • Terms: cancellation notice and any posting policy override travel with the relationship, and the order snapshots them at create.

What a relationship permits

Three fields say what this buyer may buy, and all three follow one rule: they narrow and they never widen. The product is the ceiling and the relationship works beneath it.

  • catalog_scope: which products. "*" is the whole catalog, a list is exactly what it names, and it gates by_agreement products only, because an open product is the seller declaring it needs no relationship to be seen.
  • permitted_grains: which purchase grains, narrowing the product's own grains.
  • permitted_buy_types: which buy types, narrowing the product's own.

Resolution is intersection: the effective set is what the product offers and the relationship permits. Naming something the product does not offer is a no-op rather than a grant, so nothing on a relationship can sell what the seller has not published. An empty intersection means the buyer cannot book that product at all, and it does not list for them: listing something unbuyable would have the buyer build a line, the create refuse it, and the seller take the call.

Omitting a permission, or sending it empty, is no restriction, which is what every relationship meant before the fields existed. And a buyer may hold more than one relationship with one seller: each permission is the union across them, so a record stating no restriction removes the restriction. That is not the field being ignored; an unrestricted deal genuinely does permit everything.

Disclosure is the fourth axis and the one that does not narrow: disclosure_overrides states what a buyer sees of a product it can already see, resolved per field as override(product_id) ?? override("*") ?? product.disclosure ?? published. Per field is the whole subtlety: an entry that sets only pricing_policy leaves a wildcard's avails_policy in force, so the two postures stay independent instead of one wearing two names. One product_id twice is refused 422 DUPLICATE_DISCLOSURE_OVERRIDE rather than resolved by array order. See Disclosure.

Cancellation and posting terms

Cancellation is negotiated per relationship, not published per product, so it lives here: cancellation_terms carries notice_days and an optional notes for whatever the structured field does not capture. The order snapshots the effective terms by value at create, next to the rate lock, so a later agreement change can never alter a booked order's cancellation rights. Present an agreement_id on POST /orders and its terms attach to that order; omit it and nothing attaches.

The same record may carry posting_policy_overrides, each {product_id, posting_policy} with product_id optionally "*". A make-good trigger you negotiated overrides the one the seller published, per product. The resolution happens at order create and freezes with the order, exactly as cancellation_terms does: both decide money, so both snapshot. Reconciliation reads the frozen result, never the live agreement.

Who enforces what

The platform enforces market rules: identity, catalog integrity, the price invariant, the state machine, the audit trail, settlement mechanics. Participants enforce commercial policy through agreements and their own gates: who may buy, at what rates, with what approvals and credit. VAMOS makes your policy enforceable; it does not write it for you.

Network-scoped PMP deals

A common shape for first private deals: an agreement pinned to a single network's inventory set, with the buyer defining the standing parameters (daypart mix, copy splits, lengths, rate types) that apply to every order drawn under it, the way a deal ID parameterizes a line in a DSP. On VAMOS, that is an agreement whose catalog scope is one network and whose buyer-scoped rate card carries the negotiated terms; orders under it validate against the buyer's declared parameters automatically.

PreviousThe deal model