nick-doc/02 - Data Models/SellerOffer.md

---
title: SellerOffer
tags: [data-model, postgres]
aliases: [Seller Offer, Bid, ISellerOffer]
---

# SellerOffer

> **Last updated:** 2026-06-06 — MongoDB/Mongoose fully removed; PostgreSQL + Drizzle is now the only database layer.

A seller's bid against a [[PurchaseRequest]]. Stores the proposed price, the delivery time commitment, optional notes/attachments, and a small status machine (`pending` / `accepted` / `rejected` / `withdrawn`). The parent `PurchaseRequest` keeps the array of offer ids in `offers[]` and the chosen one in `selectedOfferId`.

> [!note] Source
> `backend/src/db/schema/sellerOffer.ts` — PostgreSQL schema (Drizzle) definition

## Schema

### PostgreSQL schema (Drizzle) — `seller_offers`

Table: `seller_offers` | Schema file: `backend/src/db/schema/sellerOffer.ts`

| PG Column | Drizzle Type | Nullable | Default | Notes |
| --- | --- | --- | --- | --- |
| `id` | `uuid` PK | no | `gen_random_uuid()` | Primary key (UUID string) |
| `legacy_object_id` | `text` | yes | — | Former Mongo ObjectId; partial-unique WHERE NOT NULL |
| `seller_id` | `uuid` FK → `users` CASCADE | no | — | Maps from `sellerId` (uses user.pgId) |
| `purchase_request_id` | `uuid` FK → `purchase_requests` CASCADE | no | — | Maps from `purchaseRequestId` |
| `title` | `varchar(200)` | no | — | |
| `description` | `varchar(1000)` | no | — | |
| `price_amount` | `numeric(18,8)` | no | — | CHECK `price_amount >= 0` |
| `price_currency` | `offer_currency` enum | no | — | `USD \| EUR \| IRR \| USDT \| USDC \| TRY` |
| `delivery_time_amount` | `int` | no | — | CHECK `delivery_time_amount >= 1` |
| `delivery_time_unit` | `delivery_unit` enum | no | — | `hours \| days \| weeks` |
| `status` | `offer_status` enum | no | `pending` | `pending \| accepted \| rejected \| withdrawn \| active` |
| `attachments` | `text[]` | yes | — | |
| `notes` | `text` | yes | — | |
| `valid_until` | `timestamp with time zone` | yes | — | Maps from `validUntil` |
| `require_aml_check` | `boolean` | yes | — | |
| `aml_block_on_failure` | `boolean` | yes | — | CHECK: block requires check (AML coherence) |
| `created_at` | `timestamp with time zone` | no | `now()` | |
| `updated_at` | `timestamp with time zone` | no | `now()` | |

**Enums used:**

| Enum name | Values |
| --- | --- |
| `offer_status` | `pending`, `accepted`, `rejected`, `withdrawn`, `active` |
| `offer_currency` | `USD`, `EUR`, `IRR`, `USDT`, `USDC`, `TRY` |
| `delivery_unit` | `hours`, `days`, `weeks` |

**Constraints:**
- `CHECK (price_amount >= 0)`
- `CHECK (delivery_time_amount >= 1)`
- AML coherence check: `aml_block_on_failure = true` requires `require_aml_check = true`

**Money precision note:** `price_amount` uses `numeric(18,8)` — differs from the `numeric(38,18)` used by `payments` and `funds_ledger_entries`. This matches the Migration Guide specification for offer amounts.

**ID note:** The primary key is `id` (UUID string), not `_id`. `legacy_object_id` retains the former MongoDB ObjectId for backfill/bridging purposes only and is not used by any runtime query.

#### Postgres Indexes

| Index | Type | Notes |
| --- | --- | --- |
| `seller_id` | btree | |
| `purchase_request_id` | btree | |
| `status` | btree | |
| `created_at DESC` | btree | |
| `(purchase_request_id, seller_id)` | btree | composite |
| `legacy_object_id` | partial-unique | WHERE NOT NULL; idempotent backfill upserts |

## Domain Fields (TypeScript)

| Field | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `id` | `string` (UUID) | yes | auto | PG primary key; replaces former `_id` ObjectId |
| `sellerId` | `string` (UUID) | yes | — | user.pgId of the submitting seller |
| `purchaseRequestId` | `string` (UUID) | yes | — | Parent request |
| `title` | `string` | yes | — | Offer headline (max 200) |
| `description` | `string` | yes | — | Pitch and details (max 1000) |
| `price.amount` | `number` | yes | — | Quoted amount (min 0) |
| `price.currency` | `string` | yes | `USDT` | `USD` / `EUR` / `IRR` / `TRY` / `USDT` / `USDC` |
| `deliveryTime.amount` | `number` | yes | — | Numeric ETA (min 1) |
| `deliveryTime.unit` | `string` | yes | — | `hours` / `days` / `weeks` |
| `status` | `string` | no | `pending` | `pending` / `accepted` / `rejected` / `withdrawn` / `active` |
| `attachments[]` | `string[]` | no | — | URLs of supporting files |
| `notes` | `string` | no | — | Internal/private notes |
| `validUntil` | `Date` | no | — | Expiration |
| `requireAmlCheck` | `boolean` | no | — | AML screening required before presenting to buyer |
| `amlBlockOnFailure` | `boolean` | no | — | Block offer on AML failure (vs. flag for review) |
| `createdAt` | `Date` | auto | — | |
| `updatedAt` | `Date` | auto | — | |

> **Status enum note:** `active` is accepted by the current backend schema for marketplace/listing flows, in addition to the negotiation statuses `pending | accepted | rejected | withdrawn`.

> **Currency note:** `TRY` is supported by the oracle/depeg path through the off-chain FX provider.

## UpdateSellerOfferInput

`UpdateSellerOfferInput` does **not** include an `updatedAt` field — the column is managed automatically by the database (`now()` default; updated by the repo layer on write).

## Virtuals

None defined.

## Pre/Post Hooks

None declared (Drizzle ORM does not use Mongoose-style lifecycle hooks).

## Instance Methods

None defined.

## Static Methods

None defined.

## Service notes

### `createOffer` — eligible parent request statuses

`createOffer` in `SellerOfferService` permits offers against a `PurchaseRequest` whose status is **`pending`**, **`received_offers`**, or **`active`**. Attempts against any other status are rejected.

### `withdrawOffer()` — frontend action available

`SellerOfferService.withdrawOffer()` is not a dedicated HTTP route. The correct API path is `PUT /api/marketplace/offers/:id/status` with `{ status: 'withdrawn' }`.

The frontend exposes this via the `withdrawOffer(offerId)` action in `src/actions/marketplace.ts` (added commit 240a668). It is called from:
- `step-2-waiting-for-payment.tsx` (edit/cancel controls while `requestDetails.status === 'received_offers'`)
- `frontend/src/app/dashboard/seller/marketplace/offers/page.tsx` (Offer Management page, bulk view)

## Relationships

- **References**: [[User]] (`sellerId` = user.pgId), [[PurchaseRequest]] (`purchaseRequestId`).
- **Referenced by**: [[PurchaseRequest]] (`offers[]`, `selectedOfferId`), [[Payment]] (`sellerOfferId`), [[Chat]] (`relatedTo.id` when `relatedTo.type === 'SellerOffer'`).
- **PG FKs**: `seller_offers.seller_id → users.id CASCADE`, `seller_offers.purchase_request_id → purchase_requests.id CASCADE`.
- **Referenced by (PG)**: `payments.seller_offer_id` (polymorphic triple), `payment_quotes` (via payment join).

## State Transitions

```mermaid
stateDiagram-v2
    [*] --> pending
    pending --> accepted : buyer accepts
    pending --> rejected : buyer rejects
    pending --> withdrawn : seller cancels
    accepted --> [*]
    rejected --> [*]
    withdrawn --> [*]
```

## Common Queries

### Postgres (Drizzle)

```ts
// Offers for a request
db.select().from(sellerOffers)
  .where(eq(sellerOffers.purchaseRequestId, requestId))
  .orderBy(desc(sellerOffers.createdAt));

// Seller's pending offers
db.select().from(sellerOffers)
  .where(and(
    eq(sellerOffers.sellerId, sellerId),
    eq(sellerOffers.status, 'pending')
  ));

// Reject siblings on accept
db.update(sellerOffers)
  .set({ status: 'rejected' })
  .where(and(
    eq(sellerOffers.purchaseRequestId, purchaseRequestId),
    ne(sellerOffers.id, acceptedId),
    eq(sellerOffers.status, 'pending')
  ));

// Cleanup expired offers
db.select().from(sellerOffers)
  .where(and(
    lt(sellerOffers.validUntil, new Date()),
    eq(sellerOffers.status, 'pending')
  ));
```

Related: [[PurchaseRequest]], [[Payment]], [[User]].