Manual Prebid Controls — Frontend Integration Guide¶

This guide is the complete, frontend-facing contract for manually opening and closing the prebid window from the company console and the superadmin console, plus the new rule that the live auction cannot start while prebid is open.

Both consoles share exactly the same contract. The only differences are the REST mount (/v2/companies vs /v2/admin) and the role token used. Manual prebid controls are REST-only — unlike the live-auction controls (start / pause / resume / end), which are WebSocket staff commands.

Audience: frontend engineers integrating the auction console.

Related docs:

• Auction — full frontend integration
• Auction lifecycle control (live start / pause / resume / end)
• Auction & prebid (backend contract)
• Starting an auction (backend flow)
• Auction WebSocket events
• Subscriber prebid (WebSocket contract)

1. TL;DR¶

Roles: COMPANY and SUPERADMIN. Company tokens are scoped to auctions owned by their company; superadmin tokens can act on any auction.

The rule that matters most: the live auction may only start once the prebid window is closed. Any manual start while prebid is open is rejected server-side with BAD_REQUEST ("Close the prebid window before starting the live auction."). Drive your Start button off the closed state, not just the scheduled status.

2. Where manual controls fit in the prebid lifecycle¶

The prebid window can open and close in two ways:

Phase flow around the controls:

OPEN ──(manual close OR deadline passes)──▶ CLOSED
  ▲                                             │
  │                                             │ start path (see §6)
  └───────── (reopen is NOT allowed)            ▼
                                    approve (only when approvalRequired)
                                            │
                                            ▼
                                    Start (manual START or auto-start)

Key semantics:

• Open materializes/records the window explicitly (prebidStartAt = now, prebidEndAt = existing deadline or endOfDay(cycleEndDate)). It is only accepted while the window is still naturally open (prebidPhase === 'OPEN'); a window that has already closed cannot be reopened.
• Close pins prebidEndAt to now, immediately blocking new subscriber prebid submissions. Existing prebids keep their prebidMutabilityPolicy behavior (e.g. IMMUTABLE_CANCEL_ONLY still allows cancel-only, no edits).
• Both actions are idempotent: repeating an open on an already-open window, or a close on an already-closed window, returns 200 with the prebidOpened / prebidClosed flag set to false.
• A manual close also clears any pending automatic open job, so the auto-policy cannot re-open the window afterwards.

3. Endpoints and payloads¶

3.1 Open the prebid window¶

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

Request body — reason is optional:

{
  "reason": "Opening the prebid window early"
}

Successful 200 response (data):

{
  "auctionId": "auc_01H…",
  "cycleId": "cyc_01H…",
  "stateVersion": 9,
  "prebidStartAt": "2026-08-17T09:00:00.000Z",
  "prebidEndAt": "2026-08-19T23:59:59.999Z",
  "prebidOpened": true
}

3.2 Close the prebid window¶

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

Request body — reason is optional:

{
  "reason": "Closing the window before the live auction"
}

Successful 200 response (data):

{
  "auctionId": "auc_01H…",
  "cycleId": "cyc_01H…",
  "stateVersion": 10,
  "prebidEndAt": "2026-08-17T09:30:00.000Z",
  "prebidClosed": true
}

3.3 Response envelope¶

Both endpoints use the standard success envelope:

{
  "status": "success",
  "message": "Prebid window opened successfully.",
  "data": {}
}

("Prebid window closed successfully." for close.) Errors use the standard { status: "error", code, message } envelope with requestId.

4. Validation and business rules¶

Applies to both open and close (unless noted):

Actions that become available after a close:

• prebidPhase → CLOSED (derived; there is no prebid review state anymore — the sealed prebids are not touched until the live auction ends).
• The start path opens: when approvalRequired === true, POST .../approve moves the auction to READY, then Start; when approvalRequired === false (default) no approval is needed and the auction starts directly from SCHEDULED — see section 6.

5. Reading state and auditing¶

Poll or reconcile the console after each mutation:

GET /v2/companies/auctions/:auctionId     (COMPANY token)
GET /v2/admin/auctions/:auctionId         (SUPERADMIN token)

Relevant fields in the overview payload:

Audit trail — both actions are recorded:

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

6. The live start gate¶

The live auction can only start once the prebid window is closed. This is enforced server-side in three layers (state machine, guard helper, and the start command):

Recommended console button states¶

This replaces the previous behavior where Start was offered while prebid was still open. Keep the Close button prominent between "prebid open" and "prebid closed" so operators close the window before starting.

7. Realtime events¶

Both mutations publish an auction.state.changed event to the auction:<auctionId> room (staff and subscribers). The example abbreviates the complete payload.state to the prebid fields used by this screen:

{
  "type": "auction.state.changed",
  "id": "evt_01H…",
  "version": "1.0",
  "source": "auction-service",
  "timestamp": "2026-08-17T09:30:00.000Z",
  "sequence": 12,
  "data": {
    "auctionId": "auc_01H…",
    "cycleId": "cyc_01H…",
    "stateVersion": 10,
    "payload": {
      "transition": "prebid_closed",
      "state": {
        "status": "SCHEDULED",
        "stateVersion": 10,
        "currentPhase": "PREBID_CLOSED",
        "prebidPhase": "CLOSED",
        "prebidStartAt": "2026-08-17T08:00:00.000Z",
        "prebidEndAt": "2026-08-17T09:30:00.000Z"
      }
    }
  }
}

Subscriber impact of prebid_closed: their REST prebid calls are rejected ("Prebid window is not open.") and their currentUser.canPrebid flips to false on the next snapshot/detail fetch. Render the form as locked on the event, do not wait for a poll.

Note: subscribers who are not subscribed to the room still see the change the next time they load the auction — the REST overview is always the source of truth for cold starts.

8. Sequence diagram¶

sequenceDiagram
    participant Staff as Staff console
    participant API as REST API
    participant Svc as Auction service
    participant Room as Auction room (WS)
    participant Sub as Subscriber app

    Note over Staff,Svc: Open (optional — records the window early)
    Staff->>API: POST .../auctions/:id/prebid/open {reason}
    API->>Svc: openPrebid command
    Svc-->>API: 200 {prebidStartAt, prebidEndAt, prebidOpened: true}
    Svc-->>Room: auction.state.changed {transition: prebid_opened}

    Note over Staff,Svc: Close — required before the live auction starts
    Staff->>API: POST .../auctions/:id/prebid/close {reason}
    API->>Svc: closePrebid command
    Svc->>Svc: prebidEndAt = now, clear auto-open job
    Svc-->>API: 200 {prebidEndAt, prebidClosed: true}
    Svc-->>Room: auction.state.changed {transition: prebid_closed}
    Room-->>Sub: canPrebid = false, form locked

    Note over Staff,Svc: Approve (only when approvalRequired; else start directly)
    Staff->>API: POST .../auctions/:id/approve {reason}
    API->>Svc: approveAuction command
    Svc-->>API: 200 {auctionStatus: READY}

    Note over Staff,Svc: Live start is now possible
    Staff->>Svc: auction.status.update {status: START}
    Svc-->>Room: auction.state.changed {transition: started}

9. Recommended client flow¶

1. Fetch GET .../auctions/:auctionId → seed prebidStartAt / prebidEndAt /
   prebidPhase / auctionStatus / settings.hasPrebid / approvalRequired.
2. Subscribe to the auction room (staff: auction.subscribe with auctionId (fetch via REST)).
3. Render Open/Close buttons per the visibility table in section 6.
4. On Open tap → POST .../prebid/open → update prebidStartAt / prebidEndAt.
5. On Close tap → POST .../prebid/close → set prebidEndAt = now, prebidPhase to
   CLOSED, enable Start.
6. Reconcile with auction.state.changed (prebid_opened / prebid_closed) so all
   consoles stay in sync.
7. On reconnect → resubscribe with lastSequence, re-fetch the overview.

Event handling sketch¶

function handleFrame(frame: any) {
  if (frame.type === 'auction.state.changed') {
    const t = frame.data?.payload?.transition;
    if (t === 'prebid_opened') {
      setPrebidWindow({ open: true });
    }
    if (t === 'prebid_closed') {
      setPrebidWindow({ open: false });
      setPrebidPhase('CLOSED');
    }
    if (t === 'started') setStatus('LIVE');
  }
  if (frame.type === 'error') {
    // code in { BAD_REQUEST, FORBIDDEN, NOT_FOUND, CONFLICT, INTERNAL }
    showToast(frame.data.message);
  }
}

10. Error reference¶

11. Related¶

• Auction — full frontend integration
• Auction lifecycle control
• Auction & prebid (backend contract)
• Starting an auction
• Subscriber prebid (WebSocket)