Overview
What a dispute is and the rules that apply to all its endpoints.
A dispute is an open conflict about an order: a claim, a mediation, a cancellation request, a return request or a chargeback. The critical data is the deadline: on the marketplace, a missed action can lose the claim and hurt the seller reputation.
Where it fits in the journey: The order lifecycle.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/disputes | List disputes |
GET | /v1/disputes/{disputeId} | Get dispute |
GET | /v1/disputes/{disputeId}/messages | List messages |
POST | /v1/disputes/{disputeId}/messages | Send message |
POST | /v1/disputes/{disputeId}/actions | Act on a dispute |
All require Authorization: Bearer mk_your_api_key. See Authentication.
Type and status
type: claim, mediation, cancellation_request, return_request or chargeback.
status: open, waiting_seller, waiting_buyer, under_review, resolved or closed.
Deadline and allowed actions
deadlineAtis the earliest deadline among the mandatory seller actions.allowedActionslistsaction,mandatoryanddueAt. Only what is listed can be sent; anything else responds409.affectsReputationsays whether the dispute weighs on reputation (nullwhen the marketplace does not say).reasonhas the normalized code and the marketplace native one.- Once resolved,
resolutionhasoutcome,refundInCentsanddecidedBy.
Messages and attachments
The message text never goes in the webhook: the event only carries IDs. Read the text with List messages. Attachments and evidence are confidential assets, only for your account.
Webhooks
dispute.created, dispute.updated and dispute.message_received. See Receiving webhooks.