Update a Dispute

PATCHhttps://api.omise.co/disputes/:id

Update an open dispute by providing a response message and metadata. Submitting a message changes the dispute status from open to pending.

---

🔑API Credentials

▼

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

Dispute ID to update (path parameter). The dispute must have status "open".

Example:"dspt_test_5xuy4w91xqz7d1w9u0t"

Recommended - 1 fieldRecommended Parameters

▼

Additional - 1 fieldAdditional Parameters

▼

---

Responses

200

Successful update

Dispute updated successfully. If message was provided, status changes from "open" to "pending".

After updating:

• If message provided: Status changes to "pending" and dispute enters review process
• Upload supporting documents using POST /disputes/:id/documents
• Once pending, no further updates can be made
• Resolution typically takes 60-90 days

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid metadata format
• Metadata exceeds 15,000 characters
• Message too long

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Dispute not found.

Common causes:

• Incorrect dispute ID
• Dispute belongs to different account
• ID typo or formatting error

422

Unprocessable entity

Dispute cannot be updated.

Common causes:

• Dispute status is not "open" (already pending, won, or lost)
• Dispute is closed and cannot be modified
• Update deadline has passed

---

Code samples

cURL

curl https://api.omise.co/disputes/dspt_test_5xuy4w91xqz7d1w9u0t \
  -X PATCH \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "message=Customer received product on 2025-02-01. Tracking shows delivery confirmation." \
  -d "metadata[case_id]=CASE-12345"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

dispute = Omise::Dispute.update('dspt_test_5xuy4w91xqz7d1w9u0t', {
  message: 'Customer received product on 2025-02-01...',
  metadata: {
    case_id: 'CASE-12345'
  }
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

dispute = omise.Dispute.update('dspt_test_5xuy4w91xqz7d1w9u0t', {
    'message': 'Customer received product on 2025-02-01...',
    'metadata': {
        'case_id': 'CASE-12345'
    }
})

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const dispute = await omise.disputes.update('dspt_test_5xuy4w91xqz7d1w9u0t', {
  message: 'Customer received product on 2025-02-01...',
  metadata: {
    case_id: 'CASE-12345'
  }
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$dispute = OmiseDispute::update('dspt_test_5xuy4w91xqz7d1w9u0t', [
    'message' => 'Customer received product on 2025-02-01...',
    'metadata' => [
        'case_id' => 'CASE-12345'
    ]
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Dispute dispute = client.disputes().update("dspt_test_5xuy4w91xqz7d1w9u0t")
    .message("Customer received product on 2025-02-01...")
    .metadata("case_id", "CASE-12345")
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var dispute = await client.Disputes.Update("dspt_test_5xuy4w91xqz7d1w9u0t", new UpdateDisputeRequest
{
    Message = "Customer received product on 2025-02-01...",
    Metadata = new Dictionary<string, object>
    {
        { "case_id", "CASE-12345" }
    }
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

dispute, _ := client.UpdateDispute("dspt_test_5xuy4w91xqz7d1w9u0t", &operations.UpdateDispute{
    Message: "Customer received product on 2025-02-01...",
    Metadata: map[string]interface{}{
        "case_id": "CASE-12345",
    },
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Invalid parameters	Check message and metadata format
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Dispute not found	Check dispute ID is correct
dispute_not_open	Dispute is not open	Can only update disputes with status "open"
dispute_closed	Dispute already closed	Closed disputes cannot be modified

Status Transition

Before	After	Condition
open	pending	Message provided in update
open	open	Only metadata updated, no message

---

Try it out

Required - 1 fields

▼

id(Required)

Recommended - 1 fields

▼

Additional - 1 fields

▼