API — Deals, Orders & Grievances

Accepting an offer/bid (or Buy Now) materialises an Order. The order then moves through dispatch → buyer receipt, with a grievance backstop. Stock physically moves only at buyer receipt (deduct-on-receipt).

Deals

Method	Path	Gating	Notes
GET	/sell-leads/deals / /buy-leads/deals	requireActiveUser	My sales / purchases lists.
GET	/deals/:dealType/:id	requireActiveUser + membership	Deal detail. Seller-only fields (realisedPnl, costBasisPerKg) omitted for the buyer. Returns documents[] + a receipt summary + dealThreadId.

Orders (fulfilment + receipt)

Method	Path	Gating	Notes
GET	/orders/receipt-deals	requireActiveUser	Buyer's "awaiting receipt" orders.
GET	/orders/:id/match-candidates	requireActiveUser	Buyer's existing lots to merge into.
POST	/orders/:id/dispatch	seller	Mark DISPATCHED (fulfilment axis, status-only). Generates a Dispatch Note, notifies the buyer. No body / no lot picker — the lot was chosen at bid.
POST	/orders/:id/confirm-receipt	buyer	Create the buyer's batch (inherits GI/metrics/photos), decrement the seller lot, release the hold. Status → COMPLETED, fulfilment → DELIVERED.
POST	/orders/:id/evidence	party	Stage evidence files (images Sharp-compressed, PDFs kept). ≤8 files.
POST	/orders/:id/cancel	buyer	Cancel with reason ≥10 + evidence.
POST	/orders/:id/auto-reverse	seller	Reverse a stale still-PLACED deal (release the hold).
POST	/orders/:id/settle-off-platform	seller	Settle a stale deal outside Cropto (decrement + release).

Deduct-on-receipt

A 14-day sweep (receipt-expiry-sweep) prompts the seller to choose (never auto-cancels).

Grievances

Mounted at /api/v1/grievances (NOT under /admin) — party reads plus admin/sub-admin adjudication.

Method	Path	Gating	Notes
POST	/grievances	party	Raise (any category, PLACED → 7 days post-COMPLETED). Reason ≥20 chars + ≥1 evidence. Generates a GR PDF, notifies the counterparty.
GET	/grievances	party / admin	My grievances / the admin queue.
GET	/grievances/:id	party / admin	Timeline.
POST	/grievances/:id/{assign,review,request-info,resolve}	authorize('admin','sub-admin')	SLA-timed lifecycle; outcomes REPLACE / PARTIAL_CREDIT / REVERSE / DISMISS → RM PDF, notify both, trust hook.

• SLA timers: first response 72h, resolve 14 days; the grievance-sla-sweep job auto-escalates breaches to ESCALATED.
• Phase 1 holds no funds: PARTIAL_CREDIT is advisory ₹ only; REVERSE only unwinds stock on a still-PLACED order. Grievance is a documentation + accountability + mediation engine, not a refund engine.

Order axes

Axis	Values
status	PLACED → COMPLETED / CANCELLED / COMPLETED_OFF_PLATFORM
fulfilmentStatus	PENDING / DISPATCHED / DELIVERED (tracking reserved)
paymentStatus	OFF_PLATFORM (escrow reserved)

Terminal transitions are idempotent (same transition = no-op; a different one on a terminal order = 409). Documents are recorded in the polymorphic OrderDocument registry; transitions in the append-only OrderEvent ledger.