Skip to content

Auction And Prebid Contract

This document describes the current REST behavior for Dichit auctions with prebid enabled. Older implementation-planning notes have been removed because they described staff-visible prebid amounts that are no longer exposed before reveal.

Core Rules

  • Prebid only applies when the program/cycle effective hasPrebid setting is true.
  • Subscribers submit, update, or cancel their own prebid through the subscriber prebid endpoints.
  • Prebids are sealed: the live auction always runs, and no winner is selected from prebids before it ends. Server-side logic uses the real amounts internally (opening bid base; post-auction fallback review), but the sealed prebids become the candidate pool only after the live auction ends with no live bids.
  • Client-facing responses redact prebid amounts from staff until the live auction ends, and from subscribers until the completed auction is explicitly revealed.

Amount Visibility

Until the live auction ends (auctionStatus !== ENDED):

  • Staff/admin responses include prebid rows, but hidden prebid-derived amount fields are returned as null (prebid list amounts, auction base / leading amounts). The pre-auction "decision" flags no longer exist — the closed prebid window is a pure go-live gate with no amount review.
  • Subscribers can see their own activePrebid and latestPrebid amount.
  • Subscriber-visible bid history omits prebid entries. Live bid entries remain visible.
  • Prebid-derived leading/opening amounts are returned as null.
  • Realtime auction.prebid.created is durable and staff-only; its nullable amount is redacted while sealed.

Once the auction is ENDED:

  • Staff (company console and superadmin console) may review the sealed prebid amounts — needed for the post-auction fallback review (declare / lot among prebids when no live bids were received).
  • Subscribers still see only their own prebid until staff explicitly reveal the amounts (POST .../prebids/reveal).

After reveal:

  • Admin, company, and subscriber auction responses may include prebid amounts.
  • Bid history and candidate payloads may include prebid-derived amounts.
  • Auction payloads include prebidAmountsRevealed: true and prebidAmountsRevealedAt.

When hasPrebid is false, normal auction/live-bid amount behavior is unchanged.

Manual Open/Close Endpoints

Staff (superadmin and company owners) can manually control the prebid window, mirroring the live-auction manual controls. Both actions only apply while the auction is SCHEDULED and prebid is enabled.

POST /v2/admin/auctions/{auctionId}/prebid/open
POST /v2/companies/auctions/{auctionId}/prebid/open
POST /v2/admin/auctions/{auctionId}/prebid/close
POST /v2/companies/auctions/{auctionId}/prebid/close

{
  "reason": "Staff control"
}

Open

  • Materializes the window explicitly: sets prebidStartAt to now and prebidEndAt to the existing deadline (or endOfDay(cycleEndDate)), writes the MANUAL_OPEN_PREBID action log, and publishes auction.state.changed with payload.transition: "prebid_opened".
  • The window can only be opened while it is still naturally open (prebidPhase OPEN); a window that has already closed cannot be reopened.
  • Idempotent: opening an already-open window is a no-op (prebidOpened: false).

Close

  • Pins prebidEndAt to now, immediately blocking new subscriber prebid submissions (prebidPhase derives to CLOSED). Existing prebids keep their prebidMutabilityPolicy behavior.
  • Writes the MANUAL_CLOSE_PREBID action log and publishes auction.state.changed with payload.transition: "prebid_closed".
  • A pending auto-open-prebid job is cleared so the window stays closed.
  • Idempotent: closing an already-closed window is a no-op (prebidClosed: false).

Live start gate

The live auction can only start once the prebid window is closed. A start (auction.status.update) is rejected while prebidPhase is OPEN ("Close the prebid window before starting the live auction."). Beyond the closed window, an approval-required auction must also have been approved (moved to READY); starting a SCHEDULED approval-required auction is rejected ("Approve this auction before starting the live auction."). The closed prebid window is a pure go-live gate — there is no amount-based gate, no direct declare, lot, or prebid disqualification before the live auction runs.

After the live auction ends (ENDED), the sealed prebids become the fallback candidate pool when no live bids were received: staff can declare the lowest prebid winner or resolve a tie by lot (see auction-start.md).

Reveal Endpoint

Prebid amounts can be revealed only after the auction is completed (AuctionStatus.ENDED):

POST /v2/admin/auctions/{auctionId}/prebids/reveal
POST /v2/companies/auctions/{auctionId}/prebids/reveal

{
  "reason": "Auction completed"
}

Authorization:

  • Superadmin can reveal any completed prebid-enabled auction.
  • Company users can reveal auctions owned by their company.

Validation:

  • hasPrebid must be true.
  • Auction status must be ENDED.
  • Repeating the request after reveal is idempotent.

On first reveal the server sets prebidAmountsRevealedAt, prebidAmountsRevealedById, increments stateVersion, writes action log REVEAL_PREBIDS, and publishes auction.state.changed with payload.transition: "prebids_revealed".