// guide

Disputes and moderation

We run the process and keep the record. Your team makes every judgement, in the dashboard or through the API.

Opening a dispute

On a claimed order, the party who did not claim can dispute the claim. The order becomes disputed.
On a completed order, either party can dispute inside the dispute window. The order stays completed.
A completed order can be disputed once. A second attempt gets 409 already_disputed.

POST /v1/orders/{id}/disputesrequest

curl https://api.marketsdk.com/v1/orders/ord_.../disputes \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor": "buy_...", "reason": "The frame is cracked, which the listing did not say."}'

Stages

Dispute stages
stage	what happens	ends
`evidence`	both parties give evidence: text, and up to five HTTPS links each time	after the evidence days, or when your team closes it
`awaiting_decision`	your team reads it and decides	when your team decides
`decided`	the decision is kept with the dispute, unchangeable	never

Evidence days default to 7 (1 to 30) and decision days to 14 (1 to 60). Set them under marketplace.
When the decision days pass with no decision, the dispute is marked overdue and you get dispute.decision_overdue. It stays open: only a person decides it.
Add evidence for a party with POST /v1/disputes/{id}/evidence, giving the actor who provided it.

Deciding

A decision names who it went against, in writing. The other party wins.

POST /v1/disputes/{id}/deciderequest

curl https://api.marketsdk.com/v1/disputes/dsp_.../decide \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"against": "seller", "note": "Photos show the crack; the listing did not mention it.",
       "refund_amount": 45000, "decided_by": "sam@shop.example"}'

What a decision does
the dispute	against the party who disputed	against the other party
on a claimed order	the claim is upheld and the order completes	the claim is rejected and the order is cancelled
on a completed order	the order stays completed	the order stays completed

The party it went against gets dispute_lost on their reputation, and the other dispute_won.
With payments on, refund_amount goes back to the buyer and the rest to the seller. Left out, an upheld claim refunds nothing, a rejected claim refunds everything, and a dispute on a completed order refunds nothing.

A buyer who disputes the charge with their bank opens a card dispute, which Stripe and the bank decide. We link it to the order and show it on the marketplace dispute as card_disputes, but your decision here does not settle it, and it does not settle yours.

Flags

Any of your users can flag a listing, a seller, or a review. Send the flag from your server, with the user who reported it:

POST /v1/flagsrequest

curl https://api.marketsdk.com/v1/flags \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "lst_...", "reporter": "buy_...", "reason": "counterfeit", "note": "Logo is wrong."}'

Reasons: prohibited_item, counterfeit, scam, offensive, spam, other. Everything with open flags waits in the review queue, GET /v1/moderation/queue, the longest waiting first. The dashboard shows it under trust.

Moderation actions

Moderation actions
action	does
`dismiss`	closes the open flags and changes nothing else
`remove_content`	removes the listing or review. A removed review stops counting toward reputation.
`suspend_seller`	suspends the seller, the seller of the listing, or the seller who wrote the review. They cannot publish or take orders, and their listings leave search.
`reinstate_seller`	lifts a suspension

Each action closes the target's open flags and is logged with who acted and why: POST /v1/moderation/actions with target, action, reason, and actor, the person on your team.

Prohibited words and categories

Under marketplace, list words or phrases that may not appear in a listing's title or description, and mark categories as prohibited. A listing that breaks either cannot be published: 403 prohibited_content or category_prohibited.