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):
- Compute the reversal with
proportionalFeeReversalover the fee Stripe actually charged —chargedApplicationFeePence, i.e. commission plus any retained deemed-supply VAT — pro-rated byresolution_pence / order_total, round-half-up. Service-quote disputes pro-rate over the quoted price instead (services never take the deemed-supplier treatment). - Call
createRefundwithreverseTransfer: true. Stripe idempotency key derived from dispute id. The reversal amount is pinned against the charge's ApplicationFee rather than left to Stripe'srefund_application_feeboolean — see payments.md. - Insert a
refundsrow (return_idis nullable so dispute-only refunds don't need a synthetic return), recording the reversalcreateRefundreports Stripe executed, not the figure requested. - 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 onepanel_casesrow for it when it is the residue (isPanelResidue): the reason isservice_quality,service_scope_mismatch,service_not_deliveredorother(fraud and duplicate charges stay with the admin), the quote isdisputed(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 asecret, 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 byadmin). - 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 frompanel_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_QUORUMis 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 byPANEL_DEADLINE_HOURS(48) lapses (lapsed) and the admin is notified (dispute_admin_review_required, reasonpanel_lapsed); thelapse-panel-casesworker 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 (
resolveOpenDisputein service.ts), with rulemember_panel:refundrefunds the charged total (statusresolved_buyer),releasedismisses (statusresolved_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 inadmin_reviewand escalates the case. - Graduation and override. Until
PANEL_GRADUATION_CASES(20) panel decisions have applied since the last admin override (a query onpanel_cases, not a stored counter), a panelreleaseholds delivered work forPANEL_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 byadmin) and resets graduation. A panelrefundis 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_penceand apanel_fee_heldposting tomember_panel_payable, ledger.md) and its payment waits for a member payout rail. - Calibration. Each counted vote writes a
calibration_recordsrow of kindpanelfor its panelist (no seller;panel_vote_idnames the vote):acceptance_verdictpassand outcomereleasedwhen it agreed with the majority,failandrefundedwhen it did not (reputation.md). - Surfaces. MCP
panel_list_open,panel_get_case,panel_vote(api-mcp.md) and RESTGET /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 kinddispute) 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 earliestis_adminone, 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
refundsrow (note = chargeback_lost:<dispute id>) and, when it took everything still charged, moves the order or quote torefunded. A later buyer-side resolution then has nothing left to refund: a goods resolution refuses withorder_not_refundable, and a service dispute routes toadmin_reviewbecause the quote isrefunded.
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_PENCEcap 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 treatsellerResponded=falseas the input. - Hard expiry: 90 days from
filed_at.expireOldDisputesworker flips toexpired, 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_BPSwas 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);labelMissedAtis 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 asstatutory_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— whenfalse, every dispute routes toadmin_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.