> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getsinbad.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getsinbad.com/_mcp/server. # Disputes > Open a dispute when a trade is stuck, follow it on the trade, and close it by mutual resolution. Either side of a trade can open a dispute when the trade is stuck. A common case is a buyer who says they paid while the seller says nothing arrived. This page covers when a customer can open a dispute, what the trade shows afterwards, and how the dispute ends. ## When a customer can open a dispute A dispute can be opened only while the trade is `CREATED` or `PAID`. Whether it can be opened right away depends on the customer's side of the trade. | Customer side | Trade status | When the customer can open a dispute | | ------------- | ------------ | ------------------------------------------------------------------------------------- | | BUY | `PAID` | After the dispute window has passed, counted from the time the trade was marked paid. | | BUY | `CREATED` | Not available. The customer can cancel instead. | | SELL | `PAID` | At any time. | | SELL | `CREATED` | After the dispute window has passed, counted from the time the escrow was created. | The length of the dispute window is fixed for each trade when it is created. When the customer opens a dispute, their open trade on that side is released. A dispute opened by the merchant does not release it. ## 1. Prepare the dispute Customer disputes use the [`openDispute`](/trade-actions/open-dispute) action. Like every trade action, you prepare it, the customer's wallet signs it and you submit it. See [Trade actions](/trade-actions) and [Sign and track transactions](/transactions). Call [`POST /v1/trades/{tradeId}/actions/{action}/execution`](https://docs.getsinbad.com/api-reference/trade-actions/prepare-partner-customer-action) with the `openDispute` action. The body is optional. If you send one, it can carry a `reason`: | `reason` | Use when | | ----------------------------- | ---------------------------------------------- | | `name_does_not_match_payment` | The sender's name does not match the customer. | | `payment_not_received` | The fiat payment did not arrive. | | `other` | None of the above. | Any other value is rejected with `400 VALIDATION_ERROR`. The reason is not written on chain. Sinbad stores it with the prepared transaction and shows it on the trade after you report the matching signed transaction and Sinbad verifies it. If you never report the transaction, `dispute.reason` can stay `null`, so report every signed transaction. ## 2. Handle `TOO_EARLY` and `INVALID_STATE` If you prepare `openDispute` before the dispute window has passed, the call fails with `409 CONFLICT` and `details.reason: "TOO_EARLY"`. `details.availableAt` holds the time, in ISO 8601 format, when the action becomes available. Wait until then and prepare again. In any other state that does not allow the action, the call fails with `409 CONFLICT` and `details.reason: "INVALID_STATE"`, plus `details.action` and `details.chainStatus`. Do not retry an `INVALID_STATE` response unchanged. `availableActions` on the trade is only a hint. The real check happens when you prepare the action. See [Errors and recovery](/errors). ## 3. Read the dispute on the trade Once the dispute transaction is confirmed, the trade moves to `DISPUTED` and carries a `dispute` object: | Field | Meaning | | ----------------------------- | -------------------------------------------- | | `reason` | The reason you sent, or `null`. | | `openedByRole` | `customer` or `merchant`. | | `openedAtStatus` | `CREATED`, `PAID` or `null`. | | `openedAt`, `transactionHash` | When and by which transaction it was opened. | | `resolvedAt`, `resolution` | Filled in when the dispute ends. | Before any dispute, `dispute` is `null`. After a dispute ends, the object stays on the trade with `resolution` filled in. The trade can show `DISPUTED` later than the transaction receipt confirms. Do not submit the action again because the status has not changed yet. Chat and payment proof stay available while the trade is `DISPUTED`. See [Trade lifecycle](/trades), [Chat and images](/trade-chat) and [Payment proof](/payment-proof). You can also follow the dispute with [Webhooks](/webhooks). ## 4. Resolve by mutual resolution While the trade is `DISPUTED`, the customer can close it with the [`mutualResolveDispute`](/trade-actions/mutual-resolve-dispute) action. It is one transaction, signed by the customer only. The other side does not sign. Prepare, sign and submit it like any other trade action. Who receives the funds depends on the customer's side: | Customer side | Funds go to | Trade ends | `dispute.resolution` | | ------------- | ---------------------------------- | ---------- | -------------------- | | SELL | The buyer | `RELEASED` | `BUYER_RELEASE` | | BUY | Back to the seller who locked them | `CANCELED` | `FULL_REFUND` | ## 5. If the two sides do not agree If neither side resolves the dispute, contact Sinbad support with the trade ID and the request ID. Sinbad support can release the funds to the buyer (`BUYER_RELEASE`, trade `RELEASED`) or refund the seller who locked them (`FULL_REFUND`, trade `CANCELED`). Follow the trade and the signed `trade.updated` events for the confirmed outcome. Agree the escalation contact and the response expectations with Sinbad during onboarding. Sinbad does not promise a fixed resolution time.