# Update Dispute

Update tags on a Dispute.

Endpoint: PUT /disputes/{dispute_id}
Version: 2022-02-01
Security: BasicAuth

## Path parameters:

  - `dispute_id` (string, required)
    The ID of Dispute.

## Request fields (application/json):

  - `tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

## Response 200 fields (application/json):

  - `id` (string)
    The ID of the resource.

  - `created_at` (string)
    Timestamp of when the object was created.

  - `updated_at` (string)
    Timestamp of when the object was last updated.

  - `action` (string,null)
    The next action required to move forward with the Dispute.

  - `amount` (integer,null)
    The total amount of the Dispute (in cents).

  - `application` (string)
    ID of the Application the resource was created under.

  - `dispute_details` (object)
    Details about the Dispute received by the processor. Any data from the processor can get included.

  - `dispute_details.case_id` (string,null)
    The case number the processor has given the Dispute in their internal database.

  - `dispute_details.pin_debit_adjustment_number` (string,null)
    A number used by the processor to identify the funds that are getting disputed.

  - `dispute_details.reason_code` (string,null)
    A code used by the processor and card networks to identify why the Dispute got filed.

  - `evidence_submitted` (string)
    The status of the uploaded evidence after it has been submitted to the issuing bank. This field reflects how the Dispute is moving forward following the [submission of dispute evidence](/api/disputes/submitdisputeevidence). For more information on challenging a Dispute, see [Responding to Disputes](/guides/after-the-payment/disputes/responding-to-disputes).

Possible values are:
- INQUIRY: Updated to this value if Dispute#state is INQUIRY at the time of submission.
- CHARGEBACK: Updated to this value if Dispute#state is PENDING at the time of submission.
- NONE: No evidence has been uploaded or submitted yet.
- NOT_SUPPORTED: The processor or dispute type (Dispute#reason) does not support evidence submission.
- UNKNOWN: Occurs if evidence details couldn't be successfully processed or retrieved.
    Enum: "INQUIRY", "CHARGEBACK", "NONE", "NOT_SUPPORTED", "UNKNOWN"

  - `identity` (string)
    The ID of the seller's Identity resource. This is the Identity resource that was used to create the seller's Merchant.

  - `merchant` (string)
    The ID of the seller's Merchant resource. This is the Merchant account the Dispute was filed against.

  - `message` (string,null)
    Additional dispute details. This field is typically null.

  - `occurred_at` (string,null)
    A timestamp of when the disputed Transfer was created.

  - `reason` (string)
    The system-defined reason for the Dispute. Available values include:

- CLERICAL: An error occurred while processing the sale, or the cardholder has an issue with the transaction and refuses the goods.
- FRAUD: The cardholder claims they didn't approve or authorize the transaction. FRAUD is the primary reason disputes get created.
- INQUIRY: The issuing bank requests more information to determine if a transaction was legitimate.
- QUALITY: The cardholder has issues with the quality of the goods or services received. Reasons can include receiving damaged goods or a service that doesn't match what's promised.
- TECHNICAL: A technical issued caused the transaction to process funds incorrectly.
    Enum: "CLERICAL", "FRAUD", "INQUIRY", "QUALITY", "TECHNICAL"

  - `respond_by` (string,null)
    A timestamp of when the Merchant must respond to the Dispute.

  - `response_state` (string)
    Details the state of the Dispute and what action the Merchant needs to take. Possible values are:

- NEEDS_RESPONSE: The Merchant needs to respond to the Dispute by the Dispute#respond_by timestamp. For details on how to respond to a Dispute, see [Responding to Disputes](/guides/after-the-payment/disputes/responding-to-disputes).
- RESPONDED: The issuing bank has received the evidence and actively reviewing it. No action needed from the Merchant.
- ACCEPTED: The Merchant has accepted the Dispute. When a Dispute is accepted, you concede that the Dispute is not worth challenging or representing. For details on how to accept a Dispute, see [Accepting a Dispute](/guides/after-the-payment/disputes/accepting-disputes/).
- NO_RESPONSE_ALLOWED: The final Dispute#response_state when a Dispute is either WON or LOST.
- UNKNOWN: Occurs when testing Disputes in the sandbox on the DUMMY_V1 processor or in production on the VANTIV_V1 processor.
    Enum: "NEEDS_RESPONSE", "RESPONDED", "ACCEPTED", "NO_RESPONSE_ALLOWED", "UNKNOWN"

  - `state` (string)
    The current overall state of the Dispute. Disputes are initially created with a PENDING state. The decision of the issuing bank is final for all parties. Possible values include:

- INQUIRY: The Dispute is being reviewed by the buyer's issuing bank. No changes can be made while in this state. If a Dispute reaches this state, the bank is requesting additional information from the seller to prove the transaction was legitimate.
- PENDING: The default initial state of a Dispute. It also acts as a transitional state after an accept request is submitted. The state will eventually change based on the transaction type:
  - For a dispute on a sale: Changes to LOST when accepted.
  - For a dispute on a refund: Changes to WON when accepted. 
- LOST: The Dispute is lost, and the cardholder keeps the credit. No further changes can be made.
- WON: The Dispute is won, the credit is reversed, and funds are returned to the Merchant. No further changes can be made.
For more details, see [Dispute States](/guides/after-the-payment/disputes/dispute-states).
    Enum: "INQUIRY", "PENDING", "LOST", "WON"

  - `transfer` (string)
    ID of the Transfer resource.
    Example: "TRxxxxxxxxxxxxxxxxxx"

  - `tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

  - `_links` (object)
    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

  - `_links.adjustment_transfers` (object)

  - `_links.adjustment_transfers.href` (string)

  - `_links.application` (object)
    Link to the Application the resource was created under.

  - `_links.application.href` (string)

  - `_links.evidence` (object)

  - `_links.evidence.href` (string)

  - `_links.self` (object)
    Link to the resource that was used in the request.

  - `_links.self.href` (string)

  - `_links.transfer` (object)
    Link to the Transfers realted to the Dispute.

  - `_links.transfer.href` (string)

## Response 400 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 404 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.