The claim lifecycle in five states.
Robnu's return_claims table walks five states. Each transition is an append-only row. Each evidence is an S3-backed StorageObject. Each win writes a recovery Adjustment back to reconciliation.
- Pending → filed → acknowledged → resolved-won | resolved-lost. Five states. Append-only events.
- The daily claim sweeper (BullMQ, 0 2 * * *) promotes overdue OrderReturn rows to claim_pending.
- Won claims write a recovery Adjustment of type=chargeback against the source MarketplacePayout.
What you get.
States are explicit
No 'in_progress' soup. Each state is a typed transition with a typed event in return_claim_events. Build dashboards on this; they stay accurate as the schema evolves.
Sweeper is idempotent
The sweeper promotes overdue returns once. A second sweep on the same hour is a no-op. The kill switch WORKER_ENABLE_CLAIM_SWEEPER governs whether it runs at all.
Won and lost are equal citizens
Lost claims are not failures, they're feedback. The lost reason is logged so the discrepancy taxonomy can shift its default posture if a reason is consistently un-disputable.
Public claim API surface.
- GET /v1/claims, list with filters (status, marketplace, period).
- GET /v1/claims/:id, single claim with events + evidences.
- GET /v1/claims/stats, counts by state for dashboards.
- POST /v1/claims/:id/file, transition pending → filed.
- POST /v1/claims/:id/acknowledge, transition filed → acknowledged.
- POST /v1/claims/:id/resolve-won, transition → resolved-won, write recovery Adjustment.
- POST /v1/claims/:id/resolve-lost, transition → resolved-lost with lost_reason.
- POST /v1/claims/:id/evidence, attach a StorageObject as evidence.
Practical answers.
Yes. Reopening writes a new event with a reopen reason and transitions the claim back to filed. The audit log preserves the full history.
RBAC controls the resolve transitions. By default OWNER/ADMIN/FINANCE roles can resolve; OPERATOR can file but not resolve. SuperAdmins act through ImpersonationSession with full audit.
Try it inside your own dashboard.
Free during early access. No card. Forever free under 25 orders/day.