Dispute
- Dispute object
- Dispute State Transition
- Get Dispute Details
- Update Dispute Details
- Contest Dispute Details
- Attach Evidence to Disputes
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.)
|
|
| 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": "MerchantAccepted",
"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
Update the status and details of an existing dispute by accepting, challenging, or providing additional evidence. This endpoint allows you to respond to disputes by submitting their resolution decision and supporting documentation. Use this API call when you need to acknowledge a dispute, accept liability, or provide evidence to contest a customer's claim.
Request
Request body
{
"statusDetails": {
"resolution": "BuyerWon",
"state": "Resolved",
"reasonCode": "MerchantAccepted",
"reasonDescription": "Merchant accepted the dispute request "
},
"closureTimestamp": "20190716T162300Z"
}
Request parameters
| Name
|
Location
|
Description
|
| StatusDetails (required) Type: DisputeStatusDetails |
Body
|
Specifies the dispute state (Open/Closed), resolution (BuyerWon/SellerWon), 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": "MerchantAccepted",
"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 claim. This endpoint enables merchants to formally contest a dispute by providing relevant proof such as shipping confirmations, customer communications, or product documentation. Use this API call when you have valid grounds to dispute a customer's claim 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
|
Response
The API returns an updated Dispute object:
{
"disputeId": "P01-1111111-1111111-B123456", // APay dispute ID generated from request
"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.
Attach Evidence to Disputes
Add supporting documentation and evidence files to an existing dispute case. This endpoint allows you to upload various types of evidence such as receipts, delivery confirmations, customer correspondence, or product photos to strengthen your dispute response. Use this API call when you need to supplement your dispute case with additional documentation, either during initial submission or as follow-up evidence.
Request
Request body
{
"merchantEvidences" : [
{
"evidenceType" : "Receipt",
"fileId": "receipt_file_id",
"evidenceText" : "null",
}
]
}
Request parameters
| Name
|
Location
|
Description
|
| merchantEvidences (required) Type: list < Evidence> |
Body
|
List of evidence items supporting your case
|
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", // APay dispute ID generated from request
"chargeId": "P01-1111111-1111111-C123456",
"disputeType" : "Chargeback",
"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
},
{
"evidenceType" : "Receipt",
"fileId": receipt_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.