Subscriber Prebid Lifecycle API (v2)¶

Auction-keyed endpoints that let a subscriber place, edit, and cancel their own prebid for an auction. These are the only subscriber prebid endpoints — the legacy cycle-keyed variants (/v2/subscribers/me/cycles/:cycleId/prebid/…) have been removed in favor of this API.

Base URL¶

/v2/subscribers/me/auctions/:auctionId/prebid

Authentication¶

All endpoints require a valid JWT bearer token for a SUBSCRIBER role user.

Authorization: Bearer <token>

Business Rules¶

Lifecycle¶

place ──→ ACTIVE ──(cancel)──→ CANCELLED ──(place)──→ ACTIVE (new prebid)
              │
              └──(edit, only when MUTABLE_UNTIL_CLOSE)──→ ACTIVE (updated amount)

Rules 1–6 apply per enrolledSubscriberId: a subscriber with two enrollments in the same program holds up to one active prebid per enrollment and must pass the relevant enrolledSubscriberId on every call.

Statuses come from the AuctionPrebidStatus enum: ACTIVE, CANCELLED, DISQUALIFIED, APPLIED, SUPERSEDED.

The PrebidMutabilityPolicy enum: IMMUTABLE_CANCEL_ONLY, MUTABLE_UNTIL_CLOSE.

Fetch GET /v2/subscribers/me/auctions/:auctionId before rendering the form. For the selected enrollment, use currentUser.canPrebid and currentUser.prebidBlockedReason. Detail viewing does not require payment or live-auction participation. Placing a prebid requires payment but does not require joining the live auction.

Common Response Envelope¶

Every success response uses this shape:

{
  "status": "success", // "success" | "error" | "pending"
  "code": 200,
  "message": "...",
  "data": {/* endpoint-specific payload */},
  "error": null
}

All three mutation endpoints return the same data shape:

{
  "auctionId": "cuid2-string",
  "cycleId": "cuid2-string",
  "prebidId": "cuid2-string",
  "enrolledSubscriberId": "cuid2-string", // enrollment the prebid belongs to
  "status": "ACTIVE", // AuctionPrebidStatus
  "documentSubmissionId": "cuid2-string" | null // PDF submission created for the prebid, if any
}

Place a Prebid¶

POST /v2/subscribers/me/auctions/:auctionId/prebid¶

Creates a new active prebid for the authenticated subscriber.

Attributes¶

Path parameters¶

Body¶

{
  "enrolledSubscriberId": "cuid2-string",
  "amount": 150,
  "signatureAssetId": "cuid2-string"
}

Response 200¶

{
  "status": "success",
  "code": 200,
  "message": "Prebid placed successfully.",
  "data": {
    "auctionId": "cuid2-string",
    "cycleId": "cuid2-string",
    "prebidId": "cuid2-string",
    "status": "ACTIVE",
    "documentSubmissionId": null
  }
}

Errors¶

Coded 400s (INVALID_AMOUNT, ACTIVE_PREBID_EXISTS, PREBID_DISABLED, PREBID_NOT_OPEN) also carry the stable code as error.code. Clients must match on error.code, never on message text.

Edit a Prebid¶

PUT /v2/subscribers/me/auctions/:auctionId/prebid/:prebidId¶

Updates the amount (and optionally the signature/document) of the subscriber's active prebid.

Attributes¶

Path parameters¶

Body¶

{
  "enrolledSubscriberId": "cuid2-string",
  "amount": 140
}

Response 200¶

{
  "status": "success",
  "code": 200,
  "message": "Prebid updated successfully.",
  "data": {
    "auctionId": "cuid2-string",
    "cycleId": "cuid2-string",
    "prebidId": "cuid2-string",
    "status": "ACTIVE",
    "documentSubmissionId": "cuid2-string" | null
  }
}

Errors¶

Same as Place a Prebid plus:

Cancel a Prebid¶

DELETE /v2/subscribers/me/auctions/:auctionId/prebid/:prebidId¶

Cancels the subscriber's active prebid, freeing the subscriber to place a new one while the prebid window is still open.

Attributes¶

Path parameters¶

Query parameters¶

No request body.

Response 200¶

{
  "status": "success",
  "code": 200,
  "message": "Prebid cancelled successfully.",
  "data": {
    "auctionId": "cuid2-string",
    "cycleId": "cuid2-string",
    "prebidId": "cuid2-string",
    "status": "CANCELLED",
    "documentSubmissionId": null
  }
}

Errors¶

Same as Place a Prebid plus:

Cancellation is not restricted to IMMUTABLE_CANCEL_ONLY — it works for both mutability policies.

Typical Client Flow¶

1. GET /v2/subscribers/me/auctions/:auctionId        → read prebidEndAt, prebidPhase, enrolledSubscriberId
2. POST /v2/subscribers/me/auctions/:auctionId/prebid → place → { prebidId, enrolledSubscriberId, status: "ACTIVE" }
3. PUT  /v2/subscribers/me/auctions/:auctionId/prebid/:prebidId → edit (only if MUTABLE_UNTIL_CLOSE)
4. DELETE /v2/subscribers/me/auctions/:auctionId/prebid/:prebidId?enrolledSubscriberId=… → cancel
5. POST  /v2/subscribers/me/auctions/:auctionId/prebid → re-place after cancel, while window is open

Every call includes the enrolledSubscriberId of the enrollment being acted on (body for POST/PUT, query for DELETE).

All mutations fail with 400 Prebid window is not open. once the prebid end time passes, so the client should treat prebidEndAt from the auction detail response as the hard deadline.

Implementation Details¶

New commands¶

Added under src/application/use-cases/auctions/commands/ and exposed through makeAuctionUseCases as commands.placePrebid, commands.updatePrebid, and commands.cancelSubscriberPrebid:

All three take a required enrolledSubscriberId and resolve participation through subscriberProgramsRepository.getParticipationForCycle, which scopes subscriber_programs to that exact enrollment (AND sp.enrolled_subscriber_id = …) and returns 403 You are not part of this cycle. when the subscriber has no such enrollment in the auction's cycle. Prebid records are additionally checked for a matching enrolledSubscriberId on edit/cancel (404 Active prebid not found. on mismatch).

All three run the shared eligibility gate under a row lock (lockAuctionByAuctionId … FOR UPDATE): auction enabled, active cycle, prebid window open, bidder not disqualified, cycle payment completed, not an existing program winner, amount within [minimumBidAmount, totalAmount]. Create and update persist the same canonical two-decimal amount used by live bidding and generated documents. Sealed prebids use no current leading amount, so they are not compared with other subscribers' values or the prior editable value.

Shared prebid document pipeline¶

The ~200-line document-submission flow was extracted from commands/upsert-prebid/upsert-prebid-command.ts into src/application/use-cases/auctions/prebid-submission-helpers.ts:

• buildPrebidDocumentSubmission(...) — resolves the prebid template, validates the signature asset, gathers program/company/subscriber/address context, creates the document_submissions row + audit logs, and returns the submission IDs. Reuses the existing submission when no new signature is given.
• enqueuePrebidDocumentRendering(...) — queues PDF rendering for a fresh submission and marks it QUEUED; failures are logged, never propagated.

These helpers were extracted from the now-removed legacy cycle-keyed upsertPrebid command, so the whole subscriber prebid surface shares one document pipeline instead of drifting.

Routes¶

src/interfaces/http/routes/v2/subscribers/me/auctions/[auctionId]/prebid/

The plugin is auto-registered in production by @fastify/autoload (the [auctionId] folder maps to the :auctionId route param) and is registered explicitly in tests/helpers/make-test-app.ts for integration tests.

Tests¶

Run with:

pnpm typecheck
pnpm vitest run --config vitest.config.mts src/application/use-cases/auctions

Related Documents¶

• auction-and-prebid.md — prebid contract and amount-visibility rules
• auction-list.md — auction listing endpoints
• auction-lifecycle-config.md — PrebidMutabilityPolicy, presets, and triggers
• ../websocket/events/prebid.md — realtime prebid events
• ../../templates/rest-api.md
• ../../development/validation.md
• ../../development/authentication.md
• ../../development/error-handling.md