--- title: Dispute url: amazon-pay-api-v2/dispute.html --- * TOC {:toc} {::options toc_levels="3" /} *** Supported operations: ### Dispute object
Field
Definition
disputeId

Type: string
Unique identifier
releaseEnvironment

Type: string
The environment the Dispute object was created in (either Sandbox or Live)
chargeId

Type: string
Associated charge identifier
disputeType

Type: disputeType [Enum]
Currently only supports Chargeback
disputeAmount

Type: price
Total disputed amount
filingReason

Type: filingReason [Enum]
Why dispute was filed (Fraudulent, ProductNotReceived, etc.)
statusDetails

Type: disputeStatusDetails
Current state, resolution state, resolution reason
merchantEvidences

Type: list <Evidence>
Evidence provided by merchant
merchantResponseDeadline

Type: dateTime
Response deadline
resolutionAuthority

Type: resolutionAuthority [Enum]
Party resolving dispute (for example Amazon Pay)
creationTimestamp

Type: dateTime
Creation date/time (UTC) in ISO 8601
#### Type: price
Parameter
Description
amount

Type: string
Transaction amount
currencyCode

Type: string
Transaction currency code in ISO 4217 format

Example: USD
#### Type: disputeStatusDetails
Field
Definition
state

Type: disputeState [Enum]
Current state: UnderReview, ActionRequired, Resolved, Closed
reasonCode

Type: reasonCode [Enum]
Status reason (see State Transitions)
reasonDescription

Type: string
Human-readable status explanation
resolution

Type: resolution [Enum]
Outcome: BuyerWon, MerchantWon, NoFault (for Resolved/Closed states)
lastUpdatedTimestamp

Type: dateTime
Last status change (UTC)
#### Type: Evidence
Field
Required
Description
Supported Values
evidenceType

Type: EvidenceType [Enum]
Yes
Category (Receipt, Signature, etc.)
  • ProductDescription
  • Receipt
  • CancellationPolicy
  • CustomerSignature
  • TrackingNumber
  • CarrierName
  • DeviceId
  • DeviceName
  • DownloadDateTime
  • Other
fileId

Type: String
No
ID of uploaded evidence file
Any valid file ID
evidenceText

Type: string
No
Text-based evidence
Free-form text
#### Enums #### **disputeType**
Value
Description
Chargeback
Payment chargeback dispute
#### **filingReason**
Value
Description
ProductNotReceived
Buyer did not receive the product
ProductUnacceptable
Product is unacceptable to buyer (e.g., missing parts)
ProductNoLongerNeeded
Buyer does not need the product anymore
CreditNotProcessed
Buyer returned product but credit was not received
Overcharged
Buyer was overcharged for the product
Fraudulent
Buyer was not responsible for the transaction
SubscriptionCancelled
Buyer was charged after subscription cancellation
DuplicateCharge
Buyer was charged twice for the product
Unrecognized
Buyer does not recognize the charge
Other
Other reason ,Any other reason for dispute filing
#### **disputeState**
Value
Description
UnderReview
Investigation ongoing
ActionRequired
Needs merchant/buyer action
Resolved
Decision made (appealable)
Closed
Final state (no changes)
#### **resolution**
Value
Description
BuyerWon
Decided in buyer's favor
MerchantWon
Decided in merchant's favor
NoFault
Neither party liable
#### **evidenceType**
Value
Description
ProductDescription
Product details and specifications
Receipt
Order receipt document
CancellationPolicy
Cancellation policy document
CustomerSignature
Customer signature document
TrackingNumber
Shipping tracking number
CarrierName
Shipping carrier name
DeviceId
Device identifier for digital goods
DeviceName
Device name for digital goods
DownloadDateTime
Download timestamp for digital goods
Other
Additional evidence types
#### **resolutionAuthority**
Value
Description
AmazonPay
Amazon Pay is the authority for Dispute Resolution
### Dispute State Transition
State
Description
Resolution
Reason code
UnderReview
Investigation in progress
None
None
ActionRequired
Waiting for merchant or buyer
None
MerchantResponseRequired: Accept or contest dispute

MerchantResponseRequired: Accept or contest dispute

MerchantAdditionalEvidencesRequired:Provide more evidence

BuyerAdditionalEvidencesRequired: Waiting for buyer evidence
Resolved
Decision made (appealable)
BuyerWon
MerchantAcceptedDispute: Merchant accepted

MerchantResponseDeadlineExpired: Response deadline passed

InvestigatorResolved: Investigation complete
Resolved
Decision made (appealable)
MerchantWon
BuyerCancelled: Buyer cancelled dispute

InvestigatorResolved: Investigation complete

ChargebackFiled: Buyer has filed chargeback besides Amazon Pay A-to-z Guarantee claim.
Closed
Final state (no changes)
BuyerWon
Same as Resolved state
Closed
Final state (no changes)
MerchantWon
Same as Resolved state
### Get Dispute Details Get detailed information about a specific dispute by providing its unique dispute ID. This endpoint returns comprehensive dispute data including the dispute type, amount, status, and any associated evidence or documentation. Use this API call when you need to review specific dispute details, track dispute status, or gather information for dispute resolution. #### Request #### Response Format The API returns a Dispute object containing: * Basic dispute information (ID, type, amount, filing reason) * Transaction details (charge ID, timestamps) * Status information (state, resolution, reason codes) * Evidence submissions (merchant documentation and files) ``` { "disputeId": "P01-1111111-1111111-B123456", "chargeId": "P01-1111111-1111111-C123456", "disputeType": "Chargeback", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "Fraudulent", "filingTimestamp": "20190714T155300Z", "resolutionAuthority": "AmazonPay", "statusDetails": { "state": "Resolved", "reasonCode": "MerchantAcceptedDispute", "reasonDescription": "Merchant accepted the dispute request", "resolution": "BuyerWon", "lastUpdatedTimestamp": "20190716T156500Z" }, "resolutionAuthority": "AmazonPay", "merchantEvidences": [ { "evidenceType" : "TrackingNumber", "fileId" : null, "evidenceText": "raw text supporting merchant evidence" }, { "evidenceType": "CustomerSignature", "fileId": "customer_signature_file_id", "evidenceText": null } ], "closureTimestamp": "20190716T155300Z", "releaseEnvironment": "Live" } ``` #### Error codes Amazon Pay APIs return standard HTTP status codes and error responses. For a complete list of error codes, response formats, and handling guidelines, see the Error Handling documentation ### Update Dispute Details Submit your response through the Update Dispute API to accept a dispute when you agree the customer's chargeback is valid. #### Request #### Request body ``` { "statusDetails": { "resolution": "BuyerWon", "state": "Resolved", "reasonCode": "MerchantAcceptedDispute", "reasonDescription": "Merchant accepted the dispute request" }, "closureTimestamp": "20190716T162300Z" } ``` #### Request parameters
Name
Location
Description
StatusDetails
(required)

Type: DisputeStatusDetails
Body
Specifies the dispute state (Resolved/Closed), resolution (BuyerWon/MerchantWon/NoFault), and reason code. All fields required.
ClosureTimeStamp
(required)

Type: dateTime
Body
Required for "Closed" state only. UTC timestamp in ISO 8601 format.
#### Response The API returns an updated Dispute object containing: * Basic dispute information (ID, type, amount, filing reason) * Transaction details (charge ID, timestamps) * Updated status information (state, resolution, reason codes) * Evidence submissions (merchant documentation and files) ``` { "disputeId": "P01-1111111-1111111-B123456", "chargeId": "P01-1111111-1111111-C123456", "disputeType": "Chargeback", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "Fraudulent", "filingTimestamp": "20190714T155300Z", "resolutionAuthority": "AmazonPay", "statusDetails": { "state": "Resolved", "reasonCode": "MerchantAcceptedDispute", "reasonDescription": "Merchant accepted the dispute request", "resolution": "BuyerWon", "lastUpdatedTimestamp": "20190716T156500Z" }, "resolutionAuthority": "AmazonPay", "closureTimestamp": "20190716T155300Z", "releaseEnvironment": "Live" } ``` #### Error codes Amazon Pay APIs return standard HTTP status codes and error responses. For a complete list of error codes, response formats, and handling guidelines, see the Error Handling documentation. ### Contest Dispute Details Challenge a dispute by submitting evidence and documentation to support your case against the chargeback. This endpoint enables merchants to formally contest a dispute by providing relevant proof such as shipping confirmations, customer communications, or product documentation. Use the Contest Dispute API call when you have valid grounds to dispute a customer's chargeback and want to submit supporting evidence for review. #### Request #### Request body ``` { "merchantEvidences": [ { "evidenceType" : "TrackingNumber", "fileId": null, "evidenceText": "raw text supporting merchant evidence" }, { "evidenceType": "CustomerSignature", "fileId": "customer_signature_file_id", "evidenceText": null } ] } ``` #### Request parameters
Name
Location
Description
merchantEvidences
(required)

Type: list <Evidence >
Body
List of evidence items supporting your case

  • Each evidence item needs either fileId or evidenceText
  • See Evidence Types table for supported values
#### Response The API returns an updated Dispute object: ``` { "disputeId": "P01-1111111-1111111-B123456", "chargeId": "P01-1111111-1111111-C123456", "disputeType": "Claim", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "ProductNotReceived", "filingTimestamp": "20190714T155300Z", "statusDetails": { "state": "UnderReview", "reasonCode": null, "reasonDescription": null, "resolution": null, "lastUpdatedTimestamp": "20190714T156500Z" }, "resolutionAuthority": "AmazonPay", "releaseEnvironment": "Live", "merchantEvidences": [ { "evidenceType" : "TrackingNumber", "fileId" : null, "evidenceText": "raw text supporting merchant evidence" }, { "evidenceType": "CustomerSignature", "fileId": "customer_signature_file_id", "evidenceText": null } ] } ``` #### Error codes Amazon Pay APIs return standard HTTP status codes and error responses. For a complete list of error codes, response formats, and handling guidelines, see the Error Handling documentation.