Manage disputes
[Step 8 of 10] Buyers can create a dispute by filing an Amazon Pay A-to-z Guarantee claim or by filing a chargeback with their bank. Both methods invoke the dispute management process, which you can handle programmatically through the Dispute API instead of Seller Central. You can retrieve dispute details, submit evidence, track status, and respond to claims and chargebacks through API endpoints.
- Flow Diagram for Merchant Integration with Dispute APIs
- Receiving Dispute Notifications
- Get Dispute Details
- Update Dispute Details
- Contest Dispute Details
- Attach Evidence to Disputes
- Upload files
Flow Diagram for Merchant Integration with Dispute APIs
Receiving Dispute Notifications
When a dispute is created or its status changes, Amazon Pay sends an Instant Payment Notification (IPN) to your configured endpoint. The IPN message includes:
{
"MerchantID": "Your merchant identifier",
"ObjectType": "CHARGEBACK",
"ObjectId": "S01-0000000-0000000-C000000",
"ChargePermissionId": "S01-0000000-0000000",
"NotificationType": "STATE_CHANGE",
"NotificationId": "9b4155a0-c396-46d0-83f7-te1st2xx1234",
"NotificationVersion": "V2"
}
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 Get Dispute 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"
}
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 Update Dispute 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"
}
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 Contest Dispute 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
}
]
}
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 Attach Evidence 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",
}
]
}
Upload files
Upload and manage files for dispute evidence and other documentation needs. The Upload File API supports common file formats and provides secure upload URLs. The API provides a two-step process to upload files securely.
Step 1: Get Upload URL
First, request a secure upload URL:
Request
Request body
{
"type" : "jpg",
"purpose" : "disputeEvidence"
}
Request parameters
| Name
|
Location
|
Description
|
| x-amz-pay-idempotency-key (required) Type: String |
Header
|
Unique key to prevent duplicate uploads. For detailed guidance on creating and using idempotency keys, see Idempotency.
|
| type Type: String |
Body
|
File format (jpg, png, pdf)
|
| purpose Type: String |
Body
|
Upload reason (disputeEvidence)
|
Supported file types
| fileType
|
Description
|
| csv
|
CSV files
|
| pdf
|
PDF documents
|
| xls/xlsx
|
Excel spreadsheets
|
| doc/docx
|
Word documents
|
| ods
|
OpenDocument spreadsheets
|
| jpg/png
|
Image files
|
Response
The API returns:
{
"id": "file_sdcjscbjckndjhckj", // APay File ID generated from request
"type" : "jpg",
"purpose": "disputeEvidence",
"uploadTimestamp": 20190714T155300Z,
"url": "https://pay-api.amazon.com/v1/files/file_sdcjscbjckndjhckj/contents",
"urlExpirationTimeStamp: 20190714T155300Z
}
Step 2: Upload your file
Send your file to the returned URL:
curl "YOUR_PRESIGNED_URL" \
-X PUT \
-H "Content-Type: application/pdf" \
-T "/path/to/file"
File Requirements:
- Maximum size: 2MB
- Upload URL expires after 15 minutes
- Files must be relevant dispute evidence
After uploading, use the returned fileId when submitting dispute evidence.