Disputes & Refunds

Things don’t always go smoothly. Sometimes sellers can’t ship, buyers change their mind, or items arrive damaged. This page covers how we handle these situations — from simple cancellations to complex dispute resolution.

We’ll cover two related but distinct systems:

• Refunds: Getting money back to buyers
• Disputes: Resolving problems between buyers and sellers

Refund System

Refunds are the mechanism for returning money to buyers. They can be triggered by cancellations, dispute resolutions, or manual admin actions.

When Can Refunds Happen?

Not all order statuses allow refunds. Here’s a quick reference:

Refund Reasons

We track why each refund happened:

How Refunds Work

Under the hood, refunds follow a careful process to ensure we don’t mess up the money:

Concurrency Control

What happens if two refund requests come in at the same time? We use a locking mechanism to prevent race conditions:

interface OrderFunds {
  operationLock: 'none' | 'refund' | 'transfer'
  // ...
}

Before any refund (or transfer), we set operationLock. If it’s already set, the second request fails immediately. After the operation completes, we release the lock.

Cancellation Flow

Cancellations are the simplest way for an order to end early. They trigger automatic refunds.

Who Can Cancel?

Dispute System

Disputes handle more complex problems — items that arrived damaged, don’t match the listing, or never arrived at all. Unlike cancellations, disputes involve negotiation between buyer and seller.

Opening a Dispute

Buyers can open disputes on orders that are shipped or delivered, within 30 days of the order date.

When opening a dispute, buyers must provide:

Issue Categories

The Resolution Process

Once a dispute is open, the seller needs to respond with a proposal. Here’s how the back-and-forth works:

Dispute Outcomes

Auto-Escalation

If the seller doesn’t respond to a dispute within 2 business days (no proposals submitted), the dispute automatically escalates to dispute_escalated. This is handled by the process-dispute-lifecycle background job that runs every 2 hours.

The job queries for disputes matching these criteria:

• Status is dispute_open
• Opened more than 2 business days ago (weekends excluded)
• Seller has made zero proposals

When auto-escalated, the seller receives an issue-auto-escalated notification (distinct from the manual escalation notification) informing them that the dispute was escalated due to no response.

Platform Decision (Admin Resolution)

When a dispute is escalated, an admin resolves it via the setPlatformDecision method on OrderOrchestratorService. This follows the same state machine path as peer-resolved disputes:

1. Validation — Checks the order is in dispute_escalated status and has no existing platform decision
2. State machine transition — Uses the resolve_dispute transition (same as acceptProposal), extended with platformDecision metadata
3. Fund operations — Triggers refund/transfer via handleDisputeResolutionFunds() (best-effort; failures don’t block the resolution)
4. Event emission — Emits order.dispute_resolved with acceptedBy: "platform"

The platform decision is stored on the order’s dispute subdocument:

dispute.platformDecision = {
  outcome: string        // "full_refund" | "partial_refund" | "no_refund" | "return"
  decidedBy: string      // Admin user ID
  decidedAt: Date        // When the decision was made
  notes?: string         // Optional admin notes
}
dispute.agreedOutcome = outcome
dispute.resolvedAt = new Date()

The Return Process

For return_refund outcomes, the buyer needs to ship the item back:

API Endpoints

Cancellation Endpoints

Dispute Endpoints

Admin Dispute Endpoints

Code Locations