bitroadbitroad
Using Bitroad

Disputes

Lifecycle from filing to resolution, evidence, auto-resolution rules.

Buyers & sellers

Structured dispute resolution for buyers, with deterministic auto-classification for clear-cut cases and human admin review for ambiguous ones. Disputes sit next to the returns flow, not on top of it: a return is the buyer's first recourse; a dispute is what happens when the return path doesn't resolve cleanly (rejected, fraud claims, not-as-described disputes).

State machine

   filed → triaged ──┬──► auto_resolved_buyer
                     ├──► auto_resolved_seller
                     └──► admin_review ──┬──► resolved_buyer
                                         ├──► resolved_seller
                                         └──► resolved_split

   filed → withdrawn   (buyer-only)
   filed → expired     (90 days, hard cap)

Triage runs at file-time. The deterministic classifier either auto-resolves or routes to admin_review. While CLEARING_PANEL_ENABLED is on, a service dispute in admin_review that is the residue also opens a member panel case, which may resolve it with rule member_panel (see Member panel). There's no "buyer waits for seller response" — the seller has 72h to respond but a missing response doesn't gate buyer-side outcomes.

Auto-resolution rules

A pure function, deterministic and exhaustively tested.

Rule Effect Required
buyer_defective_within_window_with_evidence Auto-resolve buyer; full refund reason=defective AND days-since-delivery ≤ 30 AND ≥ 1 image-or-document evidence
seller_buyer_no_evidence_after_sla Auto-resolve seller (dismiss) reason=not_as_described AND seller responded within 72h AND zero buyer evidence
buyer_not_received_after_sla_no_tracking Auto-resolve buyer; full refund reason=not_received AND ((never shipped AND order placed > 7 days ago — the dispatch grace) OR (shipped > 21 days ago AND no carrier delivered event))
buyer_service_not_delivered Auto-resolve buyer; full refund reason=service_not_delivered AND zero deliverables AND the seller's delivery commitment (paid_at + quoted_eta_minutes) has passed
buyer_acceptance_failed Auto-resolve buyer; full refund Service quote, any reason: the latest deliverable's machine acceptance verdict is fail, the buyer has not acknowledged it, the block's on_fail is refund, and the acceptance deadline (deadline_at, else release_sla_at) has passed. Checked after the high-value route. See Acceptance-failure disputes
manual_admin Routes to admin queue Anything ambiguous; fraud / duplicate-charge always; high-value (> £500) always; service_quality / service_scope_mismatch unless buyer_acceptance_failed applies (subjective)
member_panel Resolved by a member panel; full refund or release Not a classifier rule: set when a panel case's decision is applied (Member panel)

Defective auto-resolution pays the full order total, matching the defective reason. Admin can split.

Schema

disputes:

Column Notes
order_id The disputed goods order. Nullable — exactly one of order_id / service_quote_id is set (check constraint). ≤ 3 active disputes per target.
service_quote_id The disputed service quote thread. Filing flips the quote to disputed and pauses its payout auto-release.
return_id Optional FK; populated when the dispute follows a return.
principal_id, agent_instance_id, delegation_id Buyer-side actor.
seller_id Denormalised.
reason Goods: not_as_described / defective / not_received. Services: service_not_delivered / service_quality / service_scope_mismatch. Either: fraud_unauthorized_charge / duplicate_charge / other. Reason family must match the target — enforced on FileDisputeInput.
summary ≤ 4 000 chars buyer free-text.
currency Snapshot of the parent order/quote charge currency (gbp | usd | eur); claimed_amount_pence and resolution_pence are minor units of it.
claimed_amount_pence Capped at order total.
status, resolution_rule, resolution_pence
seller_response_text / _at / _sla_at 72h SLA.
admin_resolved_by_principal_id, admin_override_reason Admin trail.
internal_summary, internal_summary_model_version AI summary for admin queue (NOT exposed to buyer/seller).
filed_at, triaged_at, resolved_at, withdrawn_at, expired_at Lifecycle.

dispute_evidence:

Column Notes
dispute_id FK with cascade.
uploaded_by_principal_id Buyer or seller-owner only.
kind image / document / delivery_proof / communication_log / other.
mime_type, byte_size, sha256, s3_key 25 MB per item, 200 MB per dispute. SHA-256 server-computed; immutable.
caption ≤ 500 chars.

Size is bounded twice at the boundary. The route rejects on Content-Length before the body is buffered (413 payload_too_large), and body_b64 carries a Zod .max() of MAX_BASE64_CHARS_PER_ITEM — the base64 encoding of the 25 MB per-item cap, derived in evidence-store.ts rather than restated — so an oversized upload is rejected as evidence_too_large before it is decoded into a Buffer.

Evidence bytes are not persisted or downloadable. The evidence store enforces the size caps and computes the SHA-256, but stores nothing — there is no S3 upload and no retrieval endpoint. Resolution (auto and admin) relies on the recorded metadata only (sha256, byte_size, mime_type, caption). Setting S3_BUCKET_DISPUTE_EVIDENCE does not enable persistence; it only makes every put log a loud error that the bytes were dropped.

REST surface

POST   /api/v1/orders/{id}/disputes               # buyer files
GET    /api/v1/disputes                           # principal-scoped
GET    /api/v1/disputes/{id}                      # buyer or seller-owner
POST   /api/v1/disputes/{id}/evidence             # base64 body, multipart-style
POST   /api/v1/disputes/{id}/seller-response      # gated by `respond_dispute`
POST   /api/v1/disputes/{id}/withdraw             # buyer-only

POST   /api/v1/admin/disputes/{id}/resolve        # outcome=buyer/seller/split + override_reason
POST   /api/v1/admin/disputes/{id}/reopen         # admin reopens any closed dispute
GET    /api/v1/admin/disputes                     # admin queue

Every write requires Idempotency-Key. Audit row on every write.

MCP surface

Tool R/W
disputes_file write
disputes_list read
disputes_get read
disputes_add_evidence write
disputes_withdraw write (buyer)
disputes_respond write (seller, gated by respond_dispute)

Admin tools are REST-only (admin uses cookie session; platform actors don't get MCP).

Refund routing on resolution

When a dispute resolves buyer (auto or admin):

  1. Compute the reversal with proportionalFeeReversal over the fee Stripe actually charged — chargedApplicationFeePence, i.e. commission plus any retained deemed-supply VAT — pro-rated by resolution_pence / order_total, round-half-up. Service-quote disputes pro-rate over the quoted price instead (services never take the deemed-supplier treatment).
  2. Call createRefund with reverseTransfer: true. Stripe idempotency key derived from dispute id. The reversal amount is pinned against the charge's ApplicationFee rather than left to Stripe's refund_application_fee boolean — see payments.md.
  3. Insert a refunds row (return_id is nullable so dispute-only refunds don't need a synthetic return), recording the reversal createRefund reports Stripe executed, not the figure requested.
  4. If the order was paid via a still-valid delegation envelope, credit the envelope; otherwise refund returns to the card per Stripe.

When seller wins, no refund. When split, the admin supplies resolution_pence and the same flow runs against that subtotal.

Steps 1–4 are shared with the returns rail and with admin force refund.

Admin force refund

Support can refund an order outside both rails — a legacy order, a goodwill credit, or rolling back a payment-method abuse case. From where you sit it behaves like any other refund: the seller transfer reverses, the platform fee reverses in proportion, and the money returns to whatever funded the order (your delegation envelope if it is still live, otherwise the original card). A Shopify-sourced order has the refund mirrored into the seller's Shopify account so their books match.

Force refunds are capped at the order total minus everything already refunded against it, including refunds still settling at Stripe, so overlapping refunds on one order can never exceed the original charge.

Released-payout guard (service quotes)

A service quote's payout can release to the seller (worker auto-release, buyer acknowledgement, or admin override) independently of the dispute pipeline. To stop a dispute refund from double-spending an already-released payout, the buyer-resolution path locks the quote row FOR UPDATE before touching Stripe and refuses to refund when the quote is already released, refunded, or cancelled — the dispute routes to admin_review instead, and no refunds row is written. The terminal quote update is status-guarded on the value read under the lock, so a status change that races the resolution also lands in admin_review rather than reporting a phantom success.

Filing reciprocates: a dispute filed against a quote that can no longer be paused (released / refunded / cancelled) skips triage and goes straight to admin_review (reason quote_not_pausable) — the pause flip is row-count-checked, so a quote released in the file→pause window is never auto-resolved into a refund of money that already reached the seller. (An already-disputed quote is still safely paused and triages normally.)

Acceptance-failure disputes (system-filed)

When a quote's latest deliverable still fails its machine acceptance check at the acceptance deadline, under on_fail: refund, the run-acceptance worker job files a dispute itself (disputes/acceptance-failure.ts; services.md). The row carries the buyer triple from the quote (principal_id, agent_instance_id, delegation_id), reason service_scope_mismatch, a claimed amount of the quoted price and idempotency key acceptance-failed:<quote_id>. The file runs under FOR UPDATE on the quote, which must still be delivered; at most one such dispute exists per quote. The quote is paused to disputed, one system audit row (dispute.file, route worker/run-acceptance) is written, and triage resolves it through the ordinary buyer-resolution path, so every guard above applies: a high-value quote routes to admin, a released payout is never refunded without admin review, and a tab job is reversed on the ledger. The buyer gets dispute_filed and dispute_resolved_buyer, the seller service_dispute_opened.

If an admin later resolves it for the seller, the quote returns to delivered and releases on the next tick: an acceptance dispute already filed stops the failing verdict from holding the release SLA, and the deadline pass never files twice.

Tab quotes (settlement cycles)

A service quote on the buyer's tab (settlement_cycle_id set) has no PaymentIntent of its own. A buyer-side resolution reverses it through the cycle instead (ledger.md):

Where the cycle is What a buyer-side resolution does
open, closed or capture_failed A ledger reversal and a decrement of the cycle's accrued total. No Stripe refund
capturing Refuses with settlement_cycle_capturing; the dispute routes to admin_review (triage_error)
captured or settled, credit not transferred A partial refund on the cycle's charge, run after the resolution commits
captured or settled, credit transferred The same refund plus a transfer reversal of the seller share

The released-payout guard carries over (clearing invariant 12). A tab quote that is released is never refunded by auto-resolution: filing cannot pause it, so the dispute routes to admin_review. An admin resolution (manual_admin) is the one path that may refund a released tab quote, at any credit state, because its money is still the platform's to return until the seller's transfer, and recoverable by transfer reversal after it. A split on a released tab quote leaves it released. An admin cancel of a tab quote follows the same cycle rules and still refuses a released quote.

Member panel

Tier three of performance checking (vision idea 4; RFC clearing-house.md, primitive 3, decision Q2): a panel drawn from members decides the residue the acceptance engine and verifiers cannot. Built in BTRD-260 (migration 0066) behind CLEARING_PANEL_ENABLED, default off; it requires CLEARING_MEMBERSHIP_SHADOW_ENABLED and CLEARING_CALIBRATION_ENABLED. With it off every service dispute goes to the admin queue exactly as before. Code: packages/core/src/server/panel/.

  • What it decides. Triage routes a service dispute to admin_review, then opens one panel_cases row for it when it is the residue (isPanelResidue): the reason is service_quality, service_scope_mismatch, service_not_delivered or other (fraud and duplicate charges stay with the admin), the quote is disputed (the money is in escrow), the price is at most 50 000 minor units (a deliberate ceiling, the classifier's high-value line), the latest deliverable exists and is not a secret, and either the latest deliverable's verification failed or lapsed (BTRD-259) or the job has no machine-checkable acceptance block and no verifier pass. Goods disputes stay with the admin. The acceptance-failure dispute filed after a verifier's fail is the typical case.
  • The dispute stays in the admin queue. While its case is open the dispute is admin_review, so the admin queue shows it: the admin is the fallback. An admin who resolves it first escalates the case (escalated, applied by admin).
  • Who sits. Any principal (buyer or seller; no new principal kind) whose net shadow membership units in any one currency are at least PANEL_MEMBER_MIN_UNITS (1 000), who is not the job's buyer, the fulfiller's owner or a verifier's owner on the job, and is not voting on another open case of the same job. Panelists self-select from panel_list_open; there is no assignment engine.
  • Blind to the parties. The case view (panelCaseOut, written once and tested to strip identifiers) shows the job's category, capability class, scope, requested summary, output schema and acceptance block, the latest deliverable, the buyer's reason, summary and desired outcome, and the seller's response, and no principal, store, listing, instance, quote, dispute or deliverable id, name, slug or email. Free text the parties wrote is shown as they wrote it.
  • Deciding. PANEL_QUORUM is 3 and a majority (2) decides, so a tie cannot happen. The first 3 eligible votes count; the vote that completes the quorum decides under the case's row lock. A case without its quorum by PANEL_DEADLINE_HOURS (48) lapses (lapsed) and the admin is notified (dispute_admin_review_required, reason panel_lapsed); the lapse-panel-cases worker job does this every tick, also lapses open cases whose dispute closed some other way, and retries any decision that did not apply.
  • Applying the decision. Through the same resolution the admin console runs (resolveOpenDispute in service.ts), with rule member_panel: refund refunds the charged total (status resolved_buyer), release dismisses (status resolved_seller) and puts delivered work back on the release rail. The buyer is notified as for an admin resolution. A refund the resolution must block (the payout already left) leaves the dispute in admin_review and escalates the case.
  • Graduation and override. Until PANEL_GRADUATION_CASES (20) panel decisions have applied since the last admin override (a query on panel_cases, not a stored counter), a panel release holds delivered work for PANEL_OVERRIDE_WINDOW_HOURS (24) before it releases, and the admin dispute page offers an override that refunds the buyer in full or in part while the payout is still in escrow; an override marks the case (overridden_at, applied by admin) and resets graduation. A panel refund is final at Stripe, so it has no override. After graduation a release is due at once and the override closes. The plain admin reopen is refused (panel_decided) on any panel-decided dispute.
  • Fee. The case's fee is PANEL_FEE_MINOR (300 minor units) capped at the job's platform fee (its application fee less any verifier fee), split equally across the counted votes; the indivisible remainder stays with Bitroad. It is paid from Bitroad's platform fee, which is part of the charged escrow, so the buyer's refund stays whole and the seller's payout formula is untouched: a deliberate simplification over a third fee line on the job. On a refund the fee reversal returns the platform fee to the buyer, so Bitroad funds the panel from its own revenue. Panelists are members, and members are the buyers that paid fees, with no Connect account to pay; each share is recorded as owed (panel_votes.fee_pence and a panel_fee_held posting to member_panel_payable, ledger.md) and its payment waits for a member payout rail.
  • Calibration. Each counted vote writes a calibration_records row of kind panel for its panelist (no seller; panel_vote_id names the vote): acceptance_verdict pass and outcome released when it agreed with the majority, fail and refunded when it did not (reputation.md).
  • Surfaces. MCP panel_list_open, panel_get_case, panel_vote (api-mcp.md) and REST GET /api/v1/panel/open, GET /api/v1/panel/{id}, POST /api/v1/panel/{id}/vote (api-rest.md); all 404 with the flag off. The admin dispute page shows the case and its votes (admin.md). No buyer or seller console page.

Schema: panel_cases (dispute_id unique, service_quote_id, state open / decided / lapsed / escalated, quorum_size, votes_needed, deadline_at, fee_pence, currency, decision release / refund, decided_at, applied_by panel / admin, applied_at, overridden_at) and panel_votes (case_id, panelist_principal_id, vote, reason, fee_pence, voted_at; unique per case and panelist).

Card chargebacks

A card chargeback is not a Bitroad dispute. The buyer's bank raises it through the card network, and the Stripe webhook records it in charge_disputes (payments.md). Nothing files a Bitroad dispute for it, and nothing changes a dispute's status.

  • When the order or quote already has a Bitroad dispute, its latest one gets an internal note (admin_notes, target kind dispute) when the chargeback opens and when it closes, for example [chargeback] Card chargeback opened at Stripe: du_123, £10.00, reason fraudulent. Payout held until it closes. The note is authored by the platform admin principal, the earliest is_admin one, and is skipped with a logged warning while none exists. It is admin-only and it is not evidence, so triage reads the same inputs as before. The admin dispute page lists it.
  • A lost chargeback writes a refunds row (note = chargeback_lost:<dispute id>) and, when it took everything still charged, moves the order or quote to refunded. A later buyer-side resolution then has nothing left to refund: a goods resolution refuses with order_not_refundable, and a service dispute routes to admin_review because the quote is refunded.

Internal AI summarisation

An internal summariser runs against the internal Anthropic key (getAnthropicClient({ purpose: 'internal_classifier' })):

  • Cap: 800 output tokens.
  • Persisted into disputes.internal_summary + internal_summary_model_version.
  • Same PHASE_F_AI_BUDGET_PENCE cap as anomaly explanations (shared budget).
  • Visibility: the summary is shown to admins reviewing the queue. Buyers and sellers do not see this string in any UI; the API response field exists for completeness but is not exposed in customer-facing surfaces.

SLA + expiry

  • Seller-response SLA: 72 hours from filed_at. After that, the dispute remains open but auto-resolution rules treat sellerResponded=false as the input.
  • Hard expiry: 90 days from filed_at. expireOldDisputes worker flips to expired, notifies the buyer.
  • Evidence retention:
    • Active dispute: unbounded.
    • Resolved buyer-win or seller-win: 7 years (UK consumer-rights / chargeback evidence horizon). Counsel review remains the production gate.
    • Withdrawn or expired: 30-day purge.

Privacy on the admin queue

Admin reviewing a dispute sees:

  • Buyer principal id, seller id, platform id.
  • Order line items: product_id, title, quantity.
  • All evidence metadata + captions (the file bytes themselves are not retrievable — see the evidence-store note above).
  • internal_summary (AI brief) + the buyer's free-text summary.
  • Seller response text.
  • Admin resolution amount entry.

Admin does not see (in the default queue view):

  • Buyer email address, name, postal address.

An audit-trailed unredact action, gated behind a separate admin.unredact_dispute_pii permission for fraud forensics, is not yet implemented.

Uniform returns policy (platform-wide, not seller-configurable)

Returns are uniform across every listing — sellers no longer configure a per-listing return policy. The constants live in packages/core/src/server/return-policy/validate.ts; the flow lives in packages/core/src/server/returns/service.ts.

  • 30-day change-of-mind window from delivery, FREE. Full refund, and there is no restocking fee, ever (RESTOCKING_FEE_BPS = 0; MAX_RESTOCKING_FEE_BPS was deleted). In-window returns auto-approve.
  • Return shipping is seller-funded. After a return is approved the seller must upload a prepaid label within 2 business days (labelDeadlineAt = approvedAt + 2 business days). The 21-day return-shipping clock starts at LABEL ISSUANCE (labelIssuedAt), not approval.
  • Missed-label auto-refund. If the seller misses the label deadline the buyer is auto-refunded, recovered from the seller's balance (reverseTransfer: true); labelMissedAt is stamped. The buyer is then under no obligation to return unless the seller arranges collection at its own cost within 14 days (a manual op).
  • Faulty items (CRA 2015) apply on top and run longer. Within the 30-day short-term-reject window a faulty return auto-refunds; past 30 days (up to the 6-year limitation) the claim is recorded and routed (status requested) for manual repair/replacement / price-reduction / final-rejection handling — never denied.
  • Statutory cooling-off floor keys to the BUYER's country OR the seller's (statutoryCoolingOffApplies → true when either is GB), and is snapshotted onto the return as statutory_cooling_off. (Bug fix: it previously keyed to the seller alone, wrongly denying a GB buyer buying from a US seller.) The platform's 30-day change-of-mind guarantee is uniform regardless of country.

Dispute auto-resolution rules are country-agnostic — defective and not_received outcomes rest on the platform guarantee, not on UK statute. The high-value manual-review threshold (50 000 minor units) applies at face value in every currency.

Feature flags

  • AGENT_DISPUTE_AUTO_RESOLVE_ENABLED — when false, every dispute routes to admin_review (the auto-classifier still runs but its verdict is ignored). Useful for the first weeks of operation.
  • PHASE_F_AI_BUDGET_PENCE — daily AI spend cap shared with the anomaly explanation worker; default £50/day.
  • AGENT_AI_INTERNAL_DISABLED — short-circuits internal AI for tests + emergencies.
  • CLEARING_PANEL_ENABLED — the member panel for the service-dispute residue (Member panel). Default off; with it off every service dispute goes to the admin queue as before.