Subscriber Auction Detail — REST & WebSocket Integration Guide¶

Complete contract for the subscriber auction detail screen: the REST read endpoint GET /v2/subscribers/me/auctions/:auctionId plus the realtime WebSocket events that keep that screen in sync.

Prebid is split across two transports:

• REST — all reads and writes (auction detail, prebid place/edit/cancel).
• WebSocket (/ws) — the live room: state snapshots, prebid/bid lifecycle events, announcements, presence, and phase transitions.

The WebSocket never creates or modifies prebids — REST is the source of truth for every write. The socket tells the UI what changed.

Related docs: Auction — Frontend Integration Guide · Subscriber Prebid REST · Auction participant presence and counts · WebSocket auction events · WebSocket prebid events · WebSocket protocol

1. The endpoint¶

GET /v2/subscribers/me/auctions/:auctionId

1.1 Path parameter¶

1.2 Query parameters¶

1.3 Response envelope¶

Every successful response uses the standard envelope:

{
  "status": "success",
  "code": 200,
  "message": "Auction fetched successfully.",
  "data": {}
}

1.4 Error responses¶

2. Response data — field reference¶

2.1 Top level¶

Note: leadingBidAmount and per-enrollment hasPlacedBid / bidCount / isLeadingBidder were removed from this endpoint. Live-bid leading state is served by the WebSocket snapshot and the cycle-scoped overview (GET /v2/subscribers/me/cycles/:cycleId/auction/:enrolledSubscriberId).

audience stays visible after the join window closes or the auction ends. Its counts are available to every enrolled subscriber once the window has opened:

interface SubscriberAuctionAudience {
  viewerCount: number;
  joinedParticipantCount: number;
  presentParticipantCount: number;
  bidderCount: number;
  participants: PaginatedResponse<{
    subscriberId: string;
    enrolledSubscriberId: string;
    name: string | null;
    avatar: string | null;
    joinSource: 'ONLINE' | 'FLOOR';
    joinedAt: string;
    presenceStatus: 'PRESENT' | 'LEFT';
    lastSeenAt: string | null;
  }> | null;
}

participants is populated only when at least one of the requesting subscriber's enrollments has joined the auction. It includes all durable joined participants, including the requester. joinSource records how participation was created, while joinedAt is the durable admission time. presenceStatus reflects current online or floor presence. lastSeenAt is always null for a present participant; for a participant who left, it is the most recent present-to-left transition time, or null if they have never been observed present.

2.2 settings¶

2.3 liveBids[] (visible, auction-wide)¶

2.4 announcements[]¶

2.5 joinWindow¶

Participant identities follow the conditional audience.participants rules above. Viewer identities and session audit data remain staff-only.

2.6 enrollments[]¶

One entry per enrollment of the subscriber in the program's cycle. Pick the one matching your enrolledSubscriberId — every prebid write must pass that id (see Subscriber Prebid REST).

currentUser¶

prebidBlockedReason is one of:

Viewing details does not require payment and does not require joining the live auction. Prebid placement also does not require live-auction participation. The backend rechecks eligibility when the prebid mutation is submitted.

liveBids[] (own)¶

prebids[] (own)¶

2.7 winners[]¶

3. Example response¶

{
  "status": "success",
  "code": 200,
  "message": "Auction fetched successfully.",
  "data": {
    "auctionId": "auction-id",
    "cycleId": "cycle-id",
    "cycleNumber": 3,
    "cycleStatus": "ACTIVE",
    "programId": "program-id",
    "programName": "Monthly Chit",
    "prebidDocumentRequired": true,
    "prebidDocumentTemplateVersionId": "tv-id",
    "chitId": "chit-id",
    "companyId": "company-id",
    "companyName": "Dichit",
    "companyAvatar": null,
    "companyBranch": "Kochi",
    "totalAmount": 1000000,
    "auctionStatus": "SCHEDULED",
    "prebidPhase": "OPEN",
    "currentPhase": "PREBID_OPEN",
    "liveStartedAt": null,
    "prebidEndAt": "2026-08-10T18:30:00.000Z",
    "auctionStartAt": "2026-08-11T10:00:00.000Z",
    "auctionEndAt": "2026-08-11T10:30:00.000Z",
    "auctionDurationSeconds": 1800,
    "prebidAmountsRevealed": false,
    "prebidAmountsRevealedAt": null,
    "leadingBidAmount": 20000,
    "minimumBidAmount": 25000,
    "settings": {
      "hasPrebid": true,
      "auctionBidMode": "TOTAL_VALUE_DECREASING",
      "auctionClosingMode": "DURATION_MODE",
      "auctionDurationSeconds": 1800,
      "auctionExtensionSeconds": 120,
      "auctionFirstCallSeconds": 30,
      "auctionSecondCallSeconds": 20,
      "auctionThirdCallSeconds": 10,
      "subscriberJoinGraceSeconds": 0,
      "subscriberJoinLeadSeconds": 600,
      "allowStaffOfflineBids": true,
      "prebidMutabilityPolicy": "MUTABLE_UNTIL_CLOSE",
      "auctionJoiningRule": "BEFORE_START"
    },
    "joinWindow": {
      "status": "OPEN",
      "version": 2,
      "opensAt": "2026-08-11T09:50:00.000Z",
      "openedAt": "2026-08-11T09:50:00.012Z",
      "closesAt": "2026-08-11T10:00:00.000Z",
      "closedAt": null,
      "joiningRule": "BEFORE_START"
    },
    "audience": {
      "viewerCount": 4,
      "joinedParticipantCount": 3,
      "presentParticipantCount": 2,
      "bidderCount": 1,
      "participants": null
    },
    "liveBids": [],
    "announcements": [],
    "enrollments": [
      {
        "enrolledSubscriberId": "enrolled-id",
        "invoiceStatus": "PAID",
        "currentUser": {
          "canViewDetails": true,
          "canSubscribeRealtime": true,
          "accessMode": "VIEWER",
          "hasJoined": false,
          "joinedAt": null,
          "canJoin": true,
          "joinBlockedReason": null,
          "isPrebidDisqualified": false,
          "isLiveBidDisqualified": false,
          "canPrebid": false,
          "prebidBlockedReason": "ACTIVE_PREBID_EXISTS",
          "canBid": false,
          "bidBlockedReason": "PARTICIPATION_REQUIRED",
          "hasAlreadyWonProgram": false,
          "isPaymentCompletedForCycle": true
        },
        "liveBids": [],
        "prebids": [
          {
            "id": "prebid-id",
            "amount": 25000,
            "status": "ACTIVE",
            "createdAt": "2026-08-10T12:00:00.000Z"
          }
        ]
      }
    ],
    "winners": []
  }
}

4. Related REST endpoints (same screen)¶

Full prebid write contract: Subscriber Prebid REST.

5. WebSocket — realtime contract¶

5.1 Connect & authenticate¶

wss://api.example.com/ws

Browser: Sec-WebSocket-Protocol: websocket.v1, bearer.<access-token> Native/mobile: Authorization: Bearer <access-token> header. Invalid/missing token → socket closes with code 1008.

5.2 Subscribe to the auction room¶

{
  "id": "sub-001",
  "type": "auction.subscribe",
  "version": "1.0",
  "source": "web-client",
  "data": {
    "auctionId": "auction-id",
    "enrolledSubscriberId": "enrolled-id",
    "lastSequence": 0
  }
}

enrolledSubscriberId is required for subscriber sockets. Optional lastSequence (last seen auction-level data.serverSequence) requests replay.

The server then sends, in order:

1. ack — echo with eventType, auctionId, cycleId, room.
2. auction.connected — confirmation + connectionId + heartbeatIntervalMs.
3. auction.state.snapshot — full subscriber-scoped state (initial source of truth).
4. auction.audience.snapshot — current participants and authoritative counters.

Leave with auction.unsubscribe (data.auctionId) when the screen closes.

5.3 Common envelope¶

{
  "type": "auction.state.snapshot",
  "id": "evt-1",
  "version": "1.0",
  "source": "auction-service",
  "timestamp": "2026-08-10T10:00:00.000Z",
  "sequence": 2,
  "data": {}
}

5.4 Server → Client events for this screen¶

5.5 Snapshot fields that matter for prebid¶

data.payload contains:

Frontend rule: render from currentUser.canPrebid, currentUser.prebidBlockedReason, activePrebid, and auction.prebidPhase. Never decide eligibility client-side.

5.6 Prebid lifecycle events¶

auction.prebid.created — persisted and delivered only to staff. Subscriber clients do not receive it. After the REST POST, update the current user's prebid state from the response and reconcile from a snapshot/detail fetch when needed.

auction.prebid.deleted — staff/admin deletion path only, targeted at the affected subscriber. Payload: metadata.prebidId / metadata.enrolledSubscriberId. The subscriber's own REST cancel (DELETE …/prebid/:prebidId) publishes no event — the REST response (status: "CANCELLED") is the source of truth.

auction.state.changed — schedule_changed (window open/close) recomputes the prebid form state; started means the prebid window is over.

6. Recommended integration flow¶

1. Fetch GET /v2/subscribers/me/auctions/:auctionId → render auction + prebid context (fields, settings, own prebids, admission state, and audience counts).
2. Open /ws, auction.subscribe with auctionId + enrolledSubscriberId (fetch auctionId via REST first; auction row guaranteed before READY/LIVE) (+ lastSequence on reconnect).
3. On auction.state.snapshot → adopt as the live source of truth (phase, canPrebid, activePrebid, isLeadingBidder).
4. User places a prebid: REST POST …/prebid with enrolledSubscriberId + amount (+ signatureAssetId when prebidDocumentRequired). Update UI from the REST response (prebidId, status: "ACTIVE"); reconcile from a fresh detail fetch when needed.
5. User cancels: REST DELETE …/prebid/:prebidId?enrolledSubscriberId=… — response is truth; no socket event follows.
6. Apply auction.state.changed transitions to switch prebid ⇄ live modes and update countdowns; update canPrebid from auction.bidder.disqualified.
7. During LIVE: render liveBids from REST or socket bid events; own-bid leading state from currentUser.isLeadingBidder (socket) or the cycle overview.
8. auction.unsubscribe when leaving the screen.

Reconnection¶

• Persist the last seen auction-level data.serverSequence (present on bid-activity events) and pass it back as lastSequence on resubscribe.
• Prebid events are not persisted in the replay log — after a gap, re-read own prebid state from the REST detail response or the fresh snapshot.
• The envelope-level sequence is per-connection only.