Auction Events¶

Auction events are the core of the real-time API. They let clients subscribe to a live auction, place and moderate bids, declare winners, and receive a continuously updated stream of auction state.

Reference: events/presence.md · events/system.md · errors.md · rate-limits.md

Event list¶

Client → Server (commands)¶

Server → Client¶

Contract ↔ implementation mapping

auction.subscribe¶

Description¶

Joins a live auction room and starts receiving the full realtime stream. On success the server:

1. authorizes the caller against the specific (cycleId) participation rule;
2. joins the auction:<cycleId> room and the Redis fan-out channel;
3. subscribes to the domain realtime channel;
4. registers subscriber presence (for SUBSCRIBER);
5. sends auction.connected, auction.snapshot, and presence.snapshot;
6. returns an acknowledgement with the auction identity.

Direction¶

Client → Server

Roles Allowed¶

SUBSCRIBER, COMPANY, SUPERADMIN (any role with an eligible participation or admin access to the cycle).

Permissions Required¶

auction:subscribe.

Request Schema¶

Response Schema¶

The handler returns an acknowledgement, and additionally pushes auction.connected, auction.snapshot and presence.snapshot before it.

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
  "eventType": "auction.subscribe",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "room": "auction:cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X"
  }
}

Initial server events pushed after subscribe:

{
  "type": "auction.connected",
  "requestId": "req_01HQ5BWNJ5Y1P3V0W5X0W5X0W5X",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X0",
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": {
      "connectionId": "conn_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
      "heartbeatIntervalMs": 20000
    }
  }
}

{
  "type": "auction.snapshot",
  "requestId": "req_01HQ5BWNJ5Y1P3V0W5X0W5X0W5X",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": {
      "auction": {},
      "currentUser": {},
      "onlineSubscribers": [],
      "recentBids": [],
      "lastSequence": 12
    }
  }
}

{
  "type": "presence.snapshot",
  "requestId": "req_01HQ5BWNJ5Y1P3V0W5X0W5X0W5X",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W4X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": { "onlineSubscribers": [] }
  }
}

Error Responses¶

Validation Rules¶

Example Request¶

{
  "type": "auction.subscribe",
  "requestId": "req_01HQ5BWNJ5Y1P3V0W5X0W5X0W5X",
  "data": {
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "lastSequence": 12
  }
}

Broadcast Behaviour¶

Local (unicast to the requester) — but it triggers room membership and the server-pushed initial events.

Related Events¶

• auction.unsubscribe
• auction.connected, auction.snapshot, presence.snapshot
• events/presence.md

Notes¶

• Implementation status: Implemented.
• enrolledSubscriberId is required by the subscriber authorization flow (or you retry without it and the server resolves), and omitted entirely by staff.
• Use lastSequence after reconnection to minimize the lost-event window.

Best Practices¶

• Subscribe once per auction; re-subscribe after reconnect using the last serverSequence.
• Apply the auction.snapshot as the base, then deltas.

auction.unsubscribe¶

Description¶

Ends a subscription to an auction: leaves auction:<cycleId>, removes presence, and unsubscribes from the realtime channel.

Direction¶

Client → Server

Roles Allowed¶

All subscription roles.

Permissions Required¶

auction:subscribe.

Request Schema¶

Response Schema¶

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "auction.unsubscribe",
  "data": {
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "unsubscribed": true
  }
}

Error Responses¶

Validation Rules¶

cycleId required non-empty.

Example Request¶

{
  "type": "auction.unsubscribe",
  "requestId": "req_01HQ5BXWN1Y2RX0W5X0W5X0W5X",
  "data": { "cycleId": "cyc_01HQ5BWNJ5Y1P1RX0V0X0W5X0W5X" }
}

Example Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWN1Y2RX0W5X0W5X0W5X",
  "eventType": "auction.unsubscribe",
  "data": { "cycleId": "cyc_01HQ5BWNJ5Y1P1RX0W5X0W5X0W5X", "unsubscribed": true }
}

Broadcast Behaviour¶

None, except that other connections may receive presence.left if this was the subscriber's last chunk.

Related Events¶

• auction.subscribe
• presence.left

Notes¶

• Implementation status: Implemented.
• Idempotent: unsubscribing when not subscribed returns unsubscribed: false.

Best Practices¶

• Unsubscribe when the user leaves an auction view to free resources.

auction.bid.place¶

Description¶

Places a live bid on an active auction. For SUBSCRIBER users it is their own bid. For COMPANY/SUPERADMIN (staff) it can place a bid on behalf of an offline subscriber with enrolledSubscriberId (only when settings allow). amount may be a number or a decimal string; decimal strings avoid precision loss.

Direction¶

Client → Server

Roles Allowed¶

• SUBSCRIBER — own live bid.
• COMPANY, SUPERADMIN — offline staff bid (needs enrolledSubscriberId).

Permissions Required¶

auction:bid:place for the route. Staff offline placement additionally requires auction:staff-level authority at the application layer.

Request Schema¶

Response Schema¶

The route returns the bid command result:

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "auction.bid.place",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "bidId": "bid_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X",
    "amount": 25000,
    "stateVersion": 7,
    "idempotencyKey": "bid_req_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X",
    "wasReplayed": false
  }
}

Error Responses¶

Validation Rules¶

Example Request¶

{
  "type": "auction.bid.place",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": {
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "amount": "25000",
    "idempotencyKey": "bid_req_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X"
  }
}

Example Response¶

As the Success Response above.

Broadcast Behaviour¶

A successful bid is fanned out to every subscriber of auction:<cycleId> as bid.created (leading bid) or bid.updated (outbid) — see auction.bid.created server event below. The sender sees the same events.

Related Events¶

• bid.created, bid.updated, bid.rejected
• auction.started, auction.paused, auction.resumed, auction.extended

Notes¶

• Implementation status: Implemented.
• Rate limit: 100 messages / window (overridden per-route).
• Idempotency prevents double-bids on replays: wasReplayed: true means no new bid.

Best Practices¶

• Always send idempotencyKey; reuse it on reconnect for the same bid intent.
• Use decimal strings for amount on large values to avoid FP precision issues.
• Handle bid.rejected (and wasReplayed) as non-fatal.

auction.bid.cancel¶

Description¶

Planned. Cancels/revokes a bid the client previously placed. Because a live floor bid cannot simply be undone, cancel behaviour maps to the canonical bid.deleted workflow (staff bid.mark with action: DELETE_BID) in the current build; a client-driven cancel is planned.

Direction¶

Client → Server (planned)

Roles Allowed¶

SUBSCRIBER (cancel own bid); staff may delete any bid via bid.mark.

Permissions Required¶

auction:bid:place.

Request Schema¶

Response Schema¶

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y3RX0W5X0W5X0W5X",
  "eventType": "auction.bid.cancel",
  "data": { "bidId": "bid_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X", "cancelled": true }
}

Error Responses¶

FORBIDDEN, NOT_FOUND, BAD_REQUEST, CONFLICT.

Validation Rules¶

Example Request¶

{
  "type": "auction.bid.cancel",
  "requestId": "req_01HQ5BXWYP1Y5RX0W1X0W5X0W5X0W5X",
  "data": {
    "cycleId": "cyc_01HQ5BWNJ5Y1P0X0W5X0W5X0W5X",
    "bidId": "bid_01HQ5BY3K1Z2V1Y0W5X0W5X0W5X"
  }
}

Broadcast Behaviour¶

Broadcast to the room as bid.deleted.

Related Events¶

• bid.deleted
• bid.mark (staff) — the current safe way to delete a bid

Notes¶

• Implementation status: Planned. Use bid.mark DELETE_BID (staff) today.
• Policy constraint: deleting a bid that is currently leading may not be allowed; clients should be ready for CONFLICT.

Best Practices¶

• Only cancel the client's own in-flight bids; for moderation use bid.mark.

Staff command events¶

All staff events require the auction:staff permission and a cycleId. They run the corresponding auction command and return its result (e.g. { "stateVersion": n }). Subscribers and insufficiently-permissioned users receive FORBIDDEN.

bid.mark¶

One of three actions:

reasonCode ∈ KYC_ISSUE | PAYMENT_ISSUE | ELIGIBILITY_ISSUE | RULE_VIOLATION | OTHER (required except for DELETE_BID).

Example:

{
  "type": "bid.mark",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": {
    "cycleId": "cyc_01HQ5BWNJ5Y1P0X0W5X0W5X0W5X",
    "action": "DELETE_BID",
    "bidId": "bid_01HQ5BY3K1Y1V1Y0W5X0W5X0W5X",
    "reason": "errored entry"
  }
}

winner.declare¶

winner.record_lot¶

{
  "type": "winner.record_lot",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": {
    "cycleId": "cyc_01HQ5BWNJ5Y1P0X0W5X0W5X0W5X",
    "winnerEnrolledSubscriberId": "enr_01HQ5BY3K7Z1V1Y0W5X0W5X0W5X",
    "candidateEnrolledSubscriberIds": [
      "enr_01HQ5BY3K7Z1V2Y0W5X0W5X0W5X",
      "enr_01HQ5BY3K7Z1V3Y0W5X0W5X0W5X"
    ]
  }
}

Staff event Error Responses¶

Related Events¶

auction.started, auction.paused, auction.resumed, auction.closed, bid.created, bid.deleted, bidder.disqualified, auction.winner_selected.

Server events¶

Below are the canonical server-pushed auctions. All use the standard envelope with data.auctionId, data.cycleId, optional data.stateVersion, data.occurredAt, and data.payload.

auction.connected¶

Description — Sent once by auction.subscribe. Confirms live subscription and gives the connection id + heartbeat interval.

Direction Server → Client · Roles all subscribed · Permissions – · Request N/A.

Example:

{
  "type": "auction.connected",
  "requestId": "req_01HQ5BWNJ5Y1P3V0W5X0W5X0W5X",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": {
      "connectionId": "conn_01HQ5BWNJ5Y4X5RX0W5X0W5X0W5X",
      "heartbeatIntervalMs": 20000
    }
  }
}

Related: auction.snapshot, presence.snapshot.

auction.snapshot¶

Description — the current auction state delivered right after subscribe (or merged with a replay parcel when lastSequence was provided).

Direction Server → Client · Roles all subscribed · Permissions -

Example (subscriber view):

{
  "type": "auction.snapshot",
  "requestId": "req_01HQ5BWNJ5Y1P3V0W5X0W5X0W5X",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": {
      "auction": {
        "id": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
        "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
        "status": "LIVE"
      },
      "currentUser": {
        "bidderCode": "*********3210",
        "bidAmount": "24500.00"
      },
      "onlineSubscribers": [],
      "recentBids": [],
      "lastSequence": 12
    }
  }
}

Related: auction.connected, bid.created, auction.started.

The next sections document the canonical live events, including the aliased names auction.started, auction.updated, auction.ended, auction.bid.created referenced in the user-facing contract. Use the handler on the left of the mapping table when coding.

auction.started¶

Description¶

Published when a live auction starts (the auction.status.update command with status: START succeeded, or a scheduled start ran). It marks the beginning of bidding.

Direction¶

Server → Client

Roles Allowed¶

All subscribers of the auction.

Permissions Required¶

None at the event level (delivered to room members).

Response Schema¶

Example Response¶

{
  "type": "auction.started",
  "data": {
    "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
    "stateVersion": 1,
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": { "status": "STARTED", "startedAt": "2026-08-03T10:00:00.000Z" }
  }
}

Broadcast Behaviour¶

Broadcast to auction:<cycleId> room across servers.

Related Events¶

auction.connected, auction.status.update, bid.created.

Notes¶

• Implementation status: Implemented (start-auction command publishes auction.started).
• This is the canonical event; there is no separate auction.started in the documented mapping table (it already matches).

auction.updated¶

Description¶

A contractual event representing any live auction state change (start, pause, resume, extend, close, status refresh). Because the platform emits granular events, the client contract surface auction.updated maps to the canonical server events:

• auction.status_changed — coarse status change
• auction.state_refreshed — full state refresh hint
• auction.extended — end-time extended
• auction.paused / auction.resumed — pause/resume

Direction Server → Client · Roles all subscribed.

Response Schema¶

Example Response¶

{
  "type": "auction.status_changed",
  "data": {
    "auctionId": "auc_01HQ5BWN3J5Y1P5RX0X0X5W5X",
    "cycleId": "cyc_01HQ5BWN3J5Y1P5RX0X0X5W5X",
    "stateVersion": 2,
    "occurredAt": "2026-08-03T10:01:00.000Z",
    "payload": { "status": "PAUSED", "operation": "paused" }
  }
}

Related Events / Notes¶

• This is the mapping target for the documented auction.updated. When your client wants to know "the auction state changed", handle all four canonical events.
• Consume the full state auction.snapshot on connect and apply transitions here.

auction.ended¶

An alias-facing event that means the auction has closed. The server emits the canonical auction.closed on end:

{
  "type": "auction.closed",
  "data": {
    "auctionId": "auc_01HQ6BWNJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ6BWNJ5Y1P5RX0W5X0W5X0W5X",
    "stateVersion": 9,
    "occurredAt": "2026-08-03T10:15:00.000Z",
    "payload": { "status": "CLOSED", "endedAt": "2026-08-03T10:15:00.000Z" }
  }
}

Direction Server → Client · Roles subscribed · Permissions -. Related events: auction.closed is the canonical name; auction.winner_selected, winner.declare (client command). Notes auction.ended is the documented alias for auction.closed.

auction.bid.created¶

Documented name for the bid.created server event that announces a new leading bid. The full payload is a bid activity object.

{
  "type": "bid.created",
  "requestId": "bid_req_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X",
  "data": {
    "auctionId": "auc_01HQ5BWRJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_01HQ5BWRJ5Y1P5RX0W5X0W5X0W5X",
    "stateVersion": 7,
    "occurredAt": "2026-08-03T10:00:00.000Z",
    "payload": {
      "id": "bid_01HQ5BY3J7Z2V6Y0W5X0W5X0W5X",
      "auctionId": "auc_01HQ5BWRJ3J5Y1P5RX0W5X0W5X0W5X",
      "cycleId": "cyc_01HQ5BWRJ5Y1P5RX0W5X0W5X0W5X",
      "subscriberProgramId": "enr_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X",
      "subscriberId": "sub_01HQ5BWYP1Y5RX0W5X0W5X0W5X",
      "bidderName": "Annie Mohan",
      "bidderAvatarUrl": null,
      "bidderCode": "*********3210",
      "bidAmount": "25000.00",
      "bidRank": 1,
      "isWinningBid": true,
      "status": "ACCEPTED",
      "createdAt": "2026-08-03T10:00:00.000Z",
      "serverSequence": 12
    }
  }
}

• Target-scoped: for subscriber sockets, a bid event carrying targetUserId only arrives when it matches the socket's user. (See [protocol.md]).

Handler behaviour Server → Client · Roles all subscribed · Permissions — · Broadcast to auction:<cycleId>. · Error none. Related auction.bid.place, auction.ended, bid.updated, bid.rejected.

Other server events (compact reference)¶

• Direction: Server → Client
• Roles: all subscribed
• Permissions: none at event level
• Broadcast: to auction:<id> room, across servers; subscriber filtering by targetUserId where present.
• Error Responses: none (server-pushed).
• Validation: N/A.

Example auction.extended:

{
  "type": "auction.extended",
  "data": {
    "auctionId": "auc_11HQ5BWRJ5Y1P5RX0W5X0W5X0W5X",
    "cycleId": "cyc_11HQ5BWRJ5Y1P5RX0W5X0W5X0W5X",
    "stateVersion": 8,
    "occurredAt": "2026-08-03T10:00:30.000Z",
    "payload": { "auctionEndAt": "2026-08-03T10:12:00.000Z" }
  }
}

Example bidder.disqualified:

{
  "type": "bidder.disqualified",
  "data": {
    "auctionId": "auc_11HQ0W5X1Y3P5RX0W0X0W1X0X5X",
    "cycleId": "cyc_11HQ0W5X1Y3P5RX0W0X0W1X0X5X",
    "stateVersion": 5,
    "occurredAt": "2026-08-03T10:05:00.000Z",
    "payload": { "subscriberId": "enr_...", "reason": "RULE_VIOLATION" }
  }
}

Related documents¶

• events/presence.md — presence stream inside the auction room.
• events/company.md — staff (company) role usage.
• rate-limits.md — auction.bid.place 100/min.
• errors.md — error codes.