# Update Dispute

Update tags on a Dispute.

Endpoint: PUT /disputes/{dispute_id}
Security: BasicAuth

## Path parameters:

- `dispute_id` (string, required)  
    The ID of Dispute.  
    Example: "DIgDv9764vkkEVu1suZNCDbR"

## 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"

- `_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 related 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.