← Back to product·Simulmedia VAMOS Docs·Guides: for buyers / Day-locked buys
Guides: for buyers

Day-locked buys

Direct response is day-locked by nature: every line names a specific air date, not a week. Nothing new is needed to buy that way: the day grain of the period is the whole mechanism, on the avail and on the line alike. What has not existed until now is one page that walks the path, so this is that page rather than a new mechanism.

The worked example throughout: a late night daypart product, a :15 spot, 2 units, day-locked to 2026-09-16, which falls inside ISO week 2026-W38. The rate is 1200.00 USD per unit, and the seller states 400000 households per spot.

Impressions on this page are absolute households per spot, never thousands. 400000 means four hundred thousand households for one airing of one spot.

1. Read avails at day grain

Ask for the week the date sits in. A seller carrying day-locked orders states availability per date, and the answer comes back with a day-grain period.

GET /v1/sellers/{seller}/avails?product_id=late-night&weeks=2026-W38&spot_length=15
{
  "avails": [
    {
      "product_id": "late-night",
      "period": { "grain": "day", "start": "2026-09-16" },
      "state": "available",
      "spots": { "available": 6 },
      "impressions": { "source": "seller", "stream": "linear", "hh": { "per_spot": 400000 } },
      "rates": [
        {
          "locked_rate_id": "lr_ln_gen15",
          "spot_length": 15,
          "buy_type": "non_preemptible",
          "rate_basis": "per_unit",
          "gross_rate_unit": 1200.00,
          "currency": "USD"
        }
      ]
    }
  ]
}

A week-grain answer is not a refusal, and it does not stop you booking a date. It means the seller has stated availability for the week around your date but not for the date itself, and the create will tell you so. See the warning.

2. Pin the date on the line

A line item states one period. A line whose period is {"grain": "day", "start": "..."} books that product on that date, daylocked by construction: there is no distribution step and no week for the seller to spread units across. The product has to offer the grain, by listing day in its grains; a line naming a grain it does not offer is refused 422 GRAIN_NOT_OFFERED.

POST /v1/orders
{
  "seller": "{seller}",
  "external_order_id": "dr-latenight-0916",
  "rate_version": "{the card commit the avail returned}",
  "buyer_metadata": { "advertiser_id": "adv_4c1f7a2b9e03" },
  "line_items": [
    {
      "product_id": "late-night",
      "period": { "grain": "day", "start": "2026-09-16" },
      "units": 2,
      "spot_length": 15,
      "creative_id": "crt_9c2e5b71f048",
      "rate": {
        "market_class": "scatter",
        "advertiser_class": "dr",
        "buy_type": "non_preemptible",
        "unit_cost": 1200.00,
        "locked_rate_id": "lr_ln_gen15",
        "currency": "USD"
      }
    }
  ]
}

The locked_rate_id is the one the avails read returned, unchanged. That is what the price-clearance invariant requires: a booked price is a price the seller published, cited by id, never a number you computed.

3. Submit, and reach the gate

A day-locked order runs the ordinary path. It is submitted, validated, confirmed, and it stops at seller_review like everything else: nothing airs without the seller, and a pinned date does not change that.

{ "order_id": "ord_...", "external_order_id": "dr-latenight-0916",
  "status": "submitted", "created_at": "..." }

4. Read the allocation back

allocation is authoritative per date, and on a day line it has exactly one entry: the date you pinned, carrying every accepted unit. A week or month line spreads its units across the period and comes back with several entries; a day line cannot, which is the difference you bought.

"line_items": [
  {
    "unit_id": "u-0001",
    "product_id": "late-night",
    "period": { "grain": "day", "start": "2026-09-16" },
    "status": "accepted",
    "units": 2,
    "num_accepted": 2,
    "allocation": [ { "date": "2026-09-16", "units": 2 } ]
  }
]

Two units at 1200.00 is 2400.00 USD gross, and at 400000 households per spot the line is stated to deliver 800000 households. The placement_receipt on placed carries the same date in its daylocks, because it is flat-mapped from this allocation rather than computed a second time.

The day-grain avails warning

Day-grain avails is a stated precondition of day-locked ordering, and it is softly enforced. If a day-grain line names a date with no covering day-grain avail behind it, the create succeeds and says so:

{
  "order_id": "ord_...",
  "status": "submitted",
  "warnings": [
    { "code": "DATE_GRAIN_AVAILS_MISSING", "product_id": "late-night", "dates": ["2026-09-16"] }
  ]
}

The warning names the gap and changes nothing else. The order is created, it reads back normally, and no transition on it is blocked or altered. Entries are grouped one per product, because fixing this means a conversation with the seller about a product and the dates it is missing.

Why a warning and not a refusal. A seller partway through onboarding would otherwise lose a valid order over one uncovered date, which punishes partial progress instead of surfacing it. The buy is legitimate either way: the seller has said it can sell the week, and the buyer wants one day inside it.

What this asks of a seller

If you intend to carry day-locked orders, publish avails at day grain for the dates you are willing to sell. That is the whole obligation. Publishing at week grain does not stop a buyer pinning a date, and it does not stop the order; it means every such order arrives carrying a warning that names you.

PreviousSubmit a document order