Strict Auction Lifecycle — Frontend Integration Guide¶

This guide is the frontend-facing contract for the strict auction lifecycle: prebids are sealed, no winner is selected before the live auction ends, and the pre-auction "review" stage is a pure go-live gate. It replaces the old "prebid review / live bid review" model and the prebid winner-selection features that were removed.

Both consoles (company and superadmin) share exactly the same contract; the only differences are the REST mount (/v2/companies vs /v2/admin) and the role token. Winner selection happens over WebSocket; everything else is REST.

Related docs:

• Auction — full frontend integration
• Auction lifecycle control (start / pause / resume / end)
• Manual prebid controls (open / close)
• Winner declaration (backend)
• Auction & prebid (backend contract)
• Starting an auction (backend flow)

1. The three rules that everything below follows¶

1. No winner selection before the live auction ends. Staff can never declare a winner, run a lot, or otherwise settle the cycle from prebids while the auction is still SCHEDULED/READY. Winner selection happens only after auctionStatus === ENDED.
2. A closed prebid window is a pure go-live gate. Once the prebid window closes (prebidPhase === CLOSED, deadline or manual close), the only staff path forward is starting the live round — and, when the policy requires it, approving it first. There is no amount review, no candidate list, no winner actions at that stage.
3. Prebid amounts are sealed. Staff see prebid amounts only after the live auction ends; subscribers see them only after staff explicitly reveal them (POST .../prebids/reveal, also only after end). The live auction opens with no prebid-derived base/leading amount — leadingBid is set only by live bids.

2. State model¶

A single persistent auctionStatus drives the lifecycle. The prebid window is derived from timestamps as a prebidPhase, and the approval gate is a resolved policy flag (approvalRequired). Frontends drive UI off auctionStatus + prebidPhase + approvalRequired.

auctionStatus (persisted)¶

READY is used only when the effective policy sets approvalRequired (resolved from the auction's config snapshot). With approvalRequired disabled (the default), auctions start directly from SCHEDULED and READY never appears. Approving an auction without approvalRequired is rejected.

prebidPhase (derived, not persisted)¶

The phase is orthogonal to auctionStatus; whether it matters depends on the caller's policy (e.g. a start is gated on CLOSED, canPrebid on OPEN).

3. Lifecycle walkthrough (console responsibilities)¶

PENDING
   │  POST /schedule
   ▼
SCHEDULED  (prebid window opens/closes as `prebidPhase`)
   │
   ├── approvalRequired === false  ───────────────┐
   │                                              │
   ├── approvalRequired === true                  │
   │   └── POST /approve  ──▶ READY ──────────────┤
   │                                              │
   └─────────── start path (either status) ───────┘
                     │
                     ▼
                  LIVE ──(pause/resume)──▶ PAUSED
                     │
                     └── auction ends (WS auction.end OR delayed lifecycle job)
                     ▼
                  ENDED   ◄── winner selection ONLY here
                     │        live bids exist        → auction.winner.declare from a bid
                     │        no live bids received  → sealed prebids are the fallback pool:
                     │                                  auction.winner.declare {prebidId} or
                     │                                  auction.winner.record_lot (tie at lowest)
                     │
                     ├── POST /prebids/reveal  (optional, subscriber disclosure)
                     ▼
                 COMPLETE (when every division has a declared winner)

Stage-by-stage console guidance¶

4. Prebid amount visibility matrix¶

The console overview exposes prebidAmountsRevealed: boolean and prebidAmountsRevealedAt so the UI can mirror this matrix exactly. When amounts are hidden, the API returns amount: null (fields are not omitted).

5. REST API reference¶

Base path: POST|GET|PATCH|DELETE /v2/companies/auctions/:auctionId/... (superadmin: /v2/admin/auctions/:auctionId/...).

Auth: Bearer company or superadmin token. Company tokens are scoped to auctions their company owns; superadmin tokens can act on any auction. Responses use the shared { success, message, data } envelope.

5.1 Console overview¶

GET /v2/companies|admin/auctions/:auctionId

Query params (all optional): bidPageNumber, bidPageSize, prebidPageNumber, prebidPageSize, participantPageNumber, participantPageSize (default 1 / 10).

Key data fields for the strict lifecycle:

The old pre-auction decision flags and the old reviewStatus / liveStartMode / availabilityPhase fields no longer exist in the response.

5.2 Approve auction (only when approvalRequired)¶

POST /v2/companies|admin/auctions/:auctionId/approve

Body (optional):

{
  "reason": "Prebids closed, proceeding to live round"
}

• When: auctionStatus === SCHEDULED and the resolved approvalRequired policy is true. Approving an auction whose policy does not require approval is rejected (400).
• Effect: auctionStatus → READY; the lifecycle timestamp is recalculated for the approved status; action log APPROVE is written.
• Response data: { auctionId, cycleId, status: "READY", approvalRequired, auctionStartAt }.
• Errors:
• 400 "This auction does not require approval. Approving an auction without the approval-required policy is not allowed."
• 400 "Illegal auction transition APPROVE from ... by STAFF." if the auction is not SCHEDULED.
• Approval publishes durable auction.state.changed with payload.transition: "approved" and the complete post-transition payload.state.

5.3 Manual prebid open / close¶

POST /v2/companies|admin/auctions/:auctionId/prebid/open
POST /v2/companies|admin/auctions/:auctionId/prebid/close

Body: { "reason": "..." } (optional). See the dedicated manual-prebid-controls.md doc for the full contract. Summary:

• open materializes the window (prebidStartAt = now, prebidEndAt = deadline or end-of-cycle-day). Idempotent; rejected with 400 if the window already closed.
• close pins prebidEndAt = now, immediately blocking new prebid submissions. Idempotent. After close prebidPhase derives to CLOSED.
• Response data carries prebidOpened / prebidClosed booleans and publishes auction.state.changed with transition: "prebid_opened" / "prebid_closed".

5.4 Reveal prebid amounts (subscriber disclosure)¶

POST /v2/companies|admin/auctions/:auctionId/prebids/reveal

Body: { "reason": "..." } (optional).

• When: auctionStatus === ENDED only — 400 "Prebid amounts can be revealed only after the auction ends." otherwise.
• Stamps prebidAmountsRevealedAt, publishes auction.state.changed { transition: "prebids_revealed" }. Subscribers' views unlock at this point; staff already had access at ENDED.

5.5 Action logs (audit trail)¶

GET /v2/companies|admin/auctions/:auctionId/action-logs

data.actionLogs[] with action ∈ AUCTION_ACTION_TYPES (e.g. START, AUTO_START, APPROVE, CANCEL, MANUAL_OPEN_PREBID, MANUAL_CLOSE_PREBID, DECLARE_WINNER, REVEAL_PREBIDS, ...). The removed APPROVE_LIVE_AUCTION, DISQUALIFY_PREBID_CANDIDATE, and DISQUALIFY_LIVE_BID_CANDIDATE values are no longer in the vocabulary.

5.6 Eligible winner candidates¶

GET /v2/companies|admin/auctions/:auctionId/eligible-winner-candidates?pageNumber=1&pageSize=10

Returns eligible subscribers (enrolledSubscriberId, subscriberId, name, avatar, email, mobileNumber) — used to seed the manual-declare picker after the auction ends. It does not return prebid amounts.

5.7 Schedule / reschedule¶

PATCH /v2/companies|admin/auctions/:auctionId/schedule

Body: { auctionStartAt, auctionDurationSeconds, reason, ...settings }. Response data includes prebidStartAt, prebidEndAt, auctionStartAt, prebidPhase — use it to confirm the derived window phase. Only valid from SCHEDULED.

5.8 Replace / disqualify winner (post-end)¶

There is no PATCH /winner endpoint. To replace a declared winner, disqualify the current one and then declare the next candidate via the WebSocket auction.winner.declare command (mode CANDIDATE with a different bidId / prebidId).

Disqualify:

POST /v2/companies|admin/auctions/:auctionId/winner/disqualify

• POST /winner/disqualify body: { winnerId, disqualificationReasonCode, disqualificationNote?, reason? }. Reason codes: KYC_ISSUE, PAYMENT_ISSUE, ELIGIBILITY_ISSUE, RULE_VIOLATION, OTHER.

5.9 Delete prebid¶

DELETE /v2/companies|admin/auctions/:auctionId/prebids/:prebidId

Deletes a specific prebid. No body.

6. WebSocket staff commands¶

Endpoint GET /ws, auth via sec-websocket-protocol header (websocket.v1, bearer.<token>), all commands require auction:staff permission and an auctionId.

6.1 Live controls¶

Start gate (important): START is rejected with error { code: "BAD_REQUEST" } if the prebid window is open — message "Close the prebid window before starting the live auction." — or if the auction requires approval and has not been approved — message "Approve this auction before starting the live auction." When approvalRequired is enabled, the auction must be READY to start; there is no implicit start from SCHEDULED.

6.2 Bid moderation¶

• DELETE_BID → requires bidId; reasonCode optional.
• DISQUALIFY_BIDDER → requires enrolledSubscriberId + reasonCode.

reasonCode ∈ KYC_ISSUE | PAYMENT_ISSUE | ELIGIBILITY_ISSUE | RULE_VIOLATION | OTHER. The old DISQUALIFY_CANDIDATE_AND_DECLARE_NEXT action has been removed.

6.3 Winner selection (only after the auction ends)¶

Both commands are rejected with 400 before the auction ends — there is no winner action while the window is open or while SCHEDULED/READY. Declaring a winner moves the auction to COMPLETE when the last division is filled; a prebid-fallback winner on an auction with remaining divisions reopens it to SCHEDULED for the next division.

6.4 Announcements / presence¶

7. Realtime events¶

The room broadcasts auction.state.changed with payload.transition one of:

Use stateVersion (monotonic) to order events and replace lifecycle state from the complete payload.state. Staff also receive durable auction.winner.changed events for detailed winner reconciliation.

8. Error catalog (frontend-facing messages)¶

9. Console button-state cheat sheet¶

10. What changed (frontend migration notes)¶

• Single status axis: reviewStatus + availabilityPhase + liveStartMode are gone. Drive UI off auctionStatus (+ derived prebidPhase + resolved approvalRequired).
• Approval is a gate, not a mode: the live-decision endpoint (and its APPROVE_LIVE_AUCTION action log) is removed. Use POST .../approve → READY when approvalRequired is enabled; otherwise start directly from SCHEDULED.
• Removed endpoint: prebid/disqualify-and-declare-next (and the DISQUALIFY_CANDIDATE_AND_DECLARE_NEXT auction.bid.mark action) are gone.
• Removed response fields: the four decision booleans (canDirectDeclareFromPrebid, canRunPrebidLot, canProceedToLiveAuction, liveBiddingDecisionPending), reviewStatus, liveStartMode, and availabilityPhase no longer exist.
• No implicit manual start: the Start command requires the prebid window closed, and (when approvalRequired) a prior approval — drive the Start button off auctionStatus + approvalRequired, not a review status.
• Leading bid is live-bid-only: the auction opens with leadingBid: null; a prebid never seeds the opening/base amount.
• Staff prebid visibility: prebid amounts unlock for staff at ENDED (not at window close); subscribers unlock only after reveal.