GET /v1/disputes/<dispute_id> to retrieve the dispute; check evidence_details.due_by (Unix timestamp) and evidence_details.submission_count; act well before due_by since late submissions are not accepted
Examine the reason field (e.g. fraudulent, not_as_described, credit_not_processed) to determine which evidence fields are most relevant; card network chargeback reason codes map to Stripe dispute reasons
POST /v1/disputes/<id> with the evidence object populated; relevant fields include customer_email_address, customer_name, customer_purchase_ip, billing_address, product_description, shipping_documentation, receipt, refund_policy, and customer_communication
Upload supporting files (receipts, shipping confirmations) via POST /v1/files with purpose=dispute_evidence; attach the returned file ids to the evidence object fields like shipping_documentation and receipt
Set submit=true on the same POST to simultaneously save and submit the evidence; if submit=false the evidence is saved as a draft; you can submit later via POST /v1/disputes/<id> with submit=true
Known gotchas
Once submit=true is set, the evidence is locked; you cannot revise submitted evidence; ensure all evidence is complete before submitting
File uploads for dispute evidence have size limits (check Stripe docs for current limits); compress large PDFs or images before uploading
Stripe charges a dispute fee when a dispute is created; the fee is refunded only if the dispute is won; accepting the dispute avoids the dispute fee in some cases but forfeits the payment
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp