# disputes (Coinbax API) > Source: https://developers.coinbax.com/reference/coinbax-api/disputes/ > Staging base URL: https://api-staging.coinbax.com ## Get all disputes for platform `GET /api/v1/disputes` - Auth: Bearer token - Operation ID: `DisputeController_getDisputes` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | enum ("open", "under_review", "pending_votes", "in_arbitration", "resolved") | no | Filter by dispute status | ### Example request ```bash curl https://api-staging.coinbax.com/api/v1/disputes \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Disputes retrieved successfully ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "transactionId": "550e8400-e29b-41d4-a716-446655440001", "initiatedBy": "sender", "currentTier": "tier_1_smart_contract", "status": "open", "reason": "Product not as described", "tier1CompletedAt": "2024-01-15T10:30:00Z", "tier2CompletedAt": "2024-01-16T10:30:00Z", "resolvedAt": "2024-01-17T10:30:00Z", "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50, "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "evidence": [ { "id": "string", "disputeId": "string", "submittedBy": "string", "type": "string", "title": "string", "description": {}, "content": {}, "fileUrl": {}, "fileHash": {}, "isEncrypted": true, "metadata": {}, "createdAt": "2026-01-15T12:00:00.000Z" } ] } ] ``` --- ## Create a new dispute for a transaction `POST /api/v1/disputes` - Auth: Bearer token - Operation ID: `DisputeController_createDispute` ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `transactionId` | string | yes | Transaction ID to dispute | | `initiatedBy` | enum ("sender", "receiver") | yes | Who is initiating the dispute | | `reason` | string | yes | Reason for the dispute | | `metadata` | object | no | Additional metadata | ```json { "transactionId": "550e8400-e29b-41d4-a716-446655440000", "initiatedBy": "sender", "reason": "Product not as described", "metadata": { "category": "product_quality" } } ``` ### Example request ```bash curl -X POST https://api-staging.coinbax.com/api/v1/disputes \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "transactionId": "550e8400-e29b-41d4-a716-446655440000", "initiatedBy": "sender", "reason": "Product not as described", "metadata": { "category": "product_quality" } }' ``` ### Responses **201** Dispute created successfully ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "transactionId": "550e8400-e29b-41d4-a716-446655440001", "initiatedBy": "sender", "currentTier": "tier_1_smart_contract", "status": "open", "reason": "Product not as described", "tier1CompletedAt": "2024-01-15T10:30:00Z", "tier2CompletedAt": "2024-01-16T10:30:00Z", "resolvedAt": "2024-01-17T10:30:00Z", "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50, "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "evidence": [ { "id": "string", "disputeId": "string", "submittedBy": "string", "type": "string", "title": "string", "description": {}, "content": {}, "fileUrl": {}, "fileHash": {}, "isEncrypted": true, "metadata": {}, "createdAt": "2026-01-15T12:00:00.000Z" } ] } ``` **400** Invalid request data or transaction not disputable **404** Transaction not found **409** Dispute already exists for this transaction --- ## Get dispute by ID `GET /api/v1/disputes/{id}` - Auth: Bearer token - Operation ID: `DisputeController_getDispute` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | | ### Example request ```bash curl https://api-staging.coinbax.com/api/v1/disputes/ \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Dispute found ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "transactionId": "550e8400-e29b-41d4-a716-446655440001", "initiatedBy": "sender", "currentTier": "tier_1_smart_contract", "status": "open", "reason": "Product not as described", "tier1CompletedAt": "2024-01-15T10:30:00Z", "tier2CompletedAt": "2024-01-16T10:30:00Z", "resolvedAt": "2024-01-17T10:30:00Z", "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50, "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "evidence": [ { "id": "string", "disputeId": "string", "submittedBy": "string", "type": "string", "title": "string", "description": {}, "content": {}, "fileUrl": {}, "fileHash": {}, "isEncrypted": true, "metadata": {}, "createdAt": "2026-01-15T12:00:00.000Z" } ] } ``` **404** Dispute not found --- ## Escalate dispute to next tier `POST /api/v1/disputes/{id}/escalate` - Auth: Bearer token - Operation ID: `DisputeController_escalateDispute` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | | ### Example request ```bash curl -X POST https://api-staging.coinbax.com/api/v1/disputes//escalate \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Dispute escalated successfully ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "transactionId": "550e8400-e29b-41d4-a716-446655440001", "initiatedBy": "sender", "currentTier": "tier_1_smart_contract", "status": "open", "reason": "Product not as described", "tier1CompletedAt": "2024-01-15T10:30:00Z", "tier2CompletedAt": "2024-01-16T10:30:00Z", "resolvedAt": "2024-01-17T10:30:00Z", "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50, "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "evidence": [ { "id": "string", "disputeId": "string", "submittedBy": "string", "type": "string", "title": "string", "description": {}, "content": {}, "fileUrl": {}, "fileHash": {}, "isEncrypted": true, "metadata": {}, "createdAt": "2026-01-15T12:00:00.000Z" } ] } ``` **400** Cannot escalate resolved dispute or already at highest tier **404** Dispute not found --- ## Submit evidence for a dispute `POST /api/v1/disputes/{id}/evidence` - Auth: Bearer token - Operation ID: `DisputeController_submitEvidence` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `submittedBy` | enum ("sender", "receiver") | yes | Who is submitting the evidence | | `type` | enum ("text", "image", "document", "screenshot", "communication_log", "other") | yes | Type of evidence | | `title` | string | yes | Title of the evidence | | `description` | string | no | Description of the evidence | | `content` | string | no | Text content (for text evidence) | | `fileUrl` | string | no | File URL (IPFS or storage) | | `fileHash` | string | no | Hash of the file for verification | | `isEncrypted` | boolean | no | Whether the evidence is encrypted | | `metadata` | object | no | Additional metadata | ```json { "submittedBy": "sender", "type": "screenshot", "title": "Screenshot of product defect", "description": "This shows the damaged packaging upon delivery", "content": "Conversation log...", "fileUrl": "ipfs://QmXyz123...", "fileHash": "0xabc123...", "isEncrypted": true, "metadata": { "fileSize": 1024000, "mimeType": "image/png" } } ``` ### Example request ```bash curl -X POST https://api-staging.coinbax.com/api/v1/disputes//evidence \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "submittedBy": "sender", "type": "screenshot", "title": "Screenshot of product defect", "description": "This shows the damaged packaging upon delivery", "content": "Conversation log...", "fileUrl": "ipfs://QmXyz123...", "fileHash": "0xabc123...", "isEncrypted": true, "metadata": { "fileSize": 1024000, "mimeType": "image/png" } }' ``` ### Responses **201** Evidence submitted successfully ```json { "id": "string", "disputeId": "string", "submittedBy": "string", "type": "string", "title": "string", "description": {}, "content": {}, "fileUrl": {}, "fileHash": {}, "isEncrypted": true, "metadata": {}, "createdAt": "2026-01-15T12:00:00.000Z" } ``` **400** Cannot submit evidence to resolved dispute **404** Dispute not found --- ## Resolve a dispute `POST /api/v1/disputes/{id}/resolve` - Auth: Bearer token - Operation ID: `DisputeController_resolveDispute` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `outcome` | enum ("favor_sender", "favor_receiver", "partial_refund") | yes | Outcome of the dispute | | `resolutionReason` | string | yes | Reason for the resolution | | `refundPercentage` | number | no | Refund percentage (0-100) if partial refund | ```json { "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50 } ``` ### Example request ```bash curl -X POST https://api-staging.coinbax.com/api/v1/disputes//resolve \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50 }' ``` ### Responses **200** Dispute resolved successfully ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "transactionId": "550e8400-e29b-41d4-a716-446655440001", "initiatedBy": "sender", "currentTier": "tier_1_smart_contract", "status": "open", "reason": "Product not as described", "tier1CompletedAt": "2024-01-15T10:30:00Z", "tier2CompletedAt": "2024-01-16T10:30:00Z", "resolvedAt": "2024-01-17T10:30:00Z", "outcome": "favor_sender", "resolutionReason": "Evidence clearly shows product defect", "refundPercentage": 50, "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "evidence": [ { "id": "string", "disputeId": "string", "submittedBy": "string", "type": "string", "title": "string", "description": {}, "content": {}, "fileUrl": {}, "fileHash": {}, "isEncrypted": true, "metadata": {}, "createdAt": "2026-01-15T12:00:00.000Z" } ] } ``` **400** Dispute already resolved or invalid resolution data **404** Dispute not found