type
concept
created
Tue Apr 07 2026 02:00:00 GMT+0200 (Central European Summer Time)
updated
Tue Apr 07 2026 02:00:00 GMT+0200 (Central European Summer Time)
sources
raw/articles/PRD
tags
exclusivity matching buyer-engagement urgency

48-Hour Exclusivity Window

abstract
When a surplus item matches a buyer with a score of 80 or higher, that buyer receives exclusive first-right-of-refusal for 48 hours, with a maximum of 3 sequential grants per item before it goes to open market.

Overview

The exclusivity mechanism creates urgency and rewards the best-matched buyer with a time-limited lock on surplus items. It transforms the matching algorithm's output into actionable, time-sensitive opportunities. During exclusivity, only the exclusive buyer can see and interact with the item -- it is hidden from all other buyers.

How Exclusivity Is Granted

  1. The matching algorithm runs when new surplus is ingested or buyer specs change
  2. If the highest-scoring match for a surplus item has a score >= 80, exclusivity is offered to that buyer
  3. The surplus item's status changes from available to exclusive
  4. The exclusivity_buyer_id, exclusivity_start, and exclusivity_end fields are set on the SurplusItem
  5. The buyer is immediately notified via email (regardless of their newsletter frequency setting)
  6. The countdown starts when the notification is sent, not when the surplus is listed

Rules and Constraints

Rule Value Rationale
Window duration 48 hours Enough time to evaluate, not so long that surplus sits idle
Minimum match score >= 80 Only high-quality matches justify locking inventory
Maximum sequential grants 3 per surplus item After 3 failed attempts, go to open market
Tie-breaking Higher monthly volume wins Larger buyers are more likely to complete
Visibility during exclusivity Hidden from all other buyers Only the exclusive buyer can see/interact
Reminder 12 hours before expiry Sent every 30 minutes by Celery beat check
Admin override Yes Admin can manually grant or revoke

Buyer Actions

The exclusive buyer has three options:

  1. Accept -- proceed to purchase. Status moves to reserved, then sold upon confirmation.
  2. Decline -- release immediately. The next highest-scoring buyer (if score >= 80 and grant count < 3) gets a fresh 48-hour window.
  3. Let it expire -- after 48 hours with no response, same behavior as decline.

State Machine

available
  |
  +-- (match score >= 80) --> exclusive (48hr)
  |                              |
  |                              +-- (buyer accepts) --> reserved --> sold
  |                              |
  |                              +-- (buyer declines) --> available (try next buyer)
  |                              |
  |                              +-- (48hr expires) --> available (try next buyer)
  |
  +-- (no match >= 80) --> stays available (open market)

When exclusivity expires or is declined:

Sequential Grant Logic

Each surplus item tracks how many exclusivity grants it has received. After 3 failed grants (declined or expired), the item goes to open market with no further exclusivity attempts. This prevents surplus from being locked in an indefinite exclusivity cycle.

Example timeline:

Notification Timeline

T+0:00   Surplus ingested, matching runs
T+0:01   High-score match found (score >= 80)
T+0:02   Exclusivity granted to Buyer A
T+0:02   Buyer A notified: "Exclusive access: Kraftliner 150g, 48hr window"
T+0:02   Newsletter with exclusivity badge sent immediately
T+36:00  Reminder: "12 hours remaining on your exclusive lot"
T+48:00  Exclusivity expires (Buyer A did not respond)
T+48:01  Status reverts to 'available'
T+48:01  Next buyer (Buyer B, score 78) -- does NOT get exclusivity (below 80)
T+48:01  All matched buyers notified: "New surplus available"

Celery Beat Tasks

Two scheduled tasks manage exclusivity:

  1. expire_exclusivities -- runs every 5 minutes. Finds items where status='exclusive' and exclusivity_end <= now. Either grants to next buyer or reverts to open market.
  2. send_exclusivity_reminders -- runs every 30 minutes. Finds items expiring within 12 hours and sends reminder to the exclusive buyer (with deduplication to avoid repeated reminders).

Newsletter Integration

Exclusivity notifications bypass normal newsletter scheduling rules:

Sources

Related