Use Disputes API

You can use the PayPal Disputes API to handle and resolve disputes programmatically throughout their lifecycle. This guide shows you how to gather dispute information, respond based on lifecycle stages, and automate dispute handling using webhooks.

Prerequisite

Ensure you have completed the mandatory set up procedures.

Understand dispute lifecycle stages

Every dispute goes through defined stages from creation to resolution. Understanding them helps you determine the required actions and responses at each stage.

Inquiry stage
Claim stage
Dispute resolution

The inquiry or dispute stage begins immediately when a customer files a dispute. This is a pre-claim stage designed to reduce the occurrence of chargebacks and claims. PayPal provides a platform for both parties to communicate and resolve issues directly without its intervention. This stage only applies to cases with the item/service not received (INR) and significantly not as described (SNAD) issues.The inquiry stage lasts up to 20 days unless escalated to a claim. If the dispute remains unresolved, either party can escalate it to a claim within the 20-day inquiry period. If not, PayPal considers the dispute canceled and closes the case.If you do not want to engage with buyers directly, you can opt out of the inquiry stage. In this case, all disputes are created directly in the claim stage. To opt out of the inquiry stage, contact PayPal or your PayPal account manager.For this stage, the value of dispute_life_cycle_stage parameter in Show dispute details response is INQUIRY.

The inquiry stage is only applicable for internal disputes.

If both parties cannot resolve the issue during the dispute stage, either party can escalate the dispute to PayPal within the 20-day inquiry period. This moves the dispute to the claim stage. All external and non-merchandise disputes proceed directly to the claim stage. This includes claims for incorrect charges, duplicate payments, or unauthorized transactions due to account compromise.For this stage, the value of dispute_life_cycle_stage parameter in Show dispute details response can be one of these values:

CHARGEBACK: A buyer or merchant can escalate an inquiry to a claim. This authorizes PayPal to review the case and adjudicate. During this stage, only PayPal agents can view the buyer’s notes. The buyer waits for PayPal’s response before taking further action. PayPal shares dispute details with the merchant, who can accept the claim, submit evidence to challenge the claim, or offer to resolve the dispute.
The CHARGEBACK stage is a PayPal dispute lifecycle stage, not a credit or debit card chargeback.
PRE_ARBITRATION: This is the first appeal stage for merchants. A merchant can appeal a chargeback if the outcome is not in the merchant’s favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.
ARBITRATION: This is the second appeal stage for merchants. If the first appeal is denied, a merchant can appeal a dispute for a second time. If the merchant does not appeal within the appeal period, PayPal returns the case to the resolved status in the PRE_ARBITRATION stage.

PayPal adjudicates only internal dispute cases. To resolve the claim, PayPal reviews the submitted evidence and adjudicates within 10 days in favor of either the buyer or merchant. PayPal then informs both parties about the resolution.Disputes can be resolved at any stage of the dispute lifecycle. After resolution, PayPal updates the status of the case as RESOLVED.

For external cases, the card issuer adjudicates the cases in CHARGEBACK and PRE_ARBITRATION stages based on the card network’s rules. However, the card network adjudicates the external cases in the ARBITRATION stage.

Gather dispute information

You can use the Disputes API to gather information about disputes associated with your account. The following sections describe how to list all disputes and retrieve details of a specific dispute.

List disputes

Use a valid access token and make a GET call to the /v1/customer/disputes endpoint to view all the disputes associated with an account.

You can also filter the results using query parameters. For example, use the disputed_transaction_id query parameter to show disputes for a specific transaction. For information on query parameters, see API reference.

curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

A successful call returns a 200 OK response. The response includes the following parameter:

Parameter	Description	Further action
`items[].dispute_id` string	Unique identifier for the dispute.	Use this value to retrieve the dispute details and respond to the dispute.

For information on all response parameters, see API reference.

Show dispute details

Use a valid access token and make a GET call to the /v1/customer/disputes/{id} endpoint to retrieve details of a specific dispute. Path parameter: {id} is the dispute_id returned in the List disputes response.

curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

A successful call returns a 200 OK response. The response includes the following parameters:

Parameter	Description	Further action
`dispute_id` string	Unique identifier for the dispute.	Use this value to respond to a dispute.
`reason` string	Reason for the dispute. For more information about the dispute reasons, see Dispute reasons.	Use this value to determine and provide the required evidence.
`status` string	Current status of the dispute. Possible values: `OPEN`, `WAITING_FOR_SELLER_RESPONSE`, `WAITING_FOR_BUYER_RESPONSE`, `UNDER_REVIEW`, `RESOLVED`. PayPal may request additional evidence multiple times throughout the dispute’s lifecycle and the `WAITING_FOR_SELLER_RESPONSE` status indicates that you need to provide evidence.	Use this value to determine your response to a dispute.
`dispute_life_cycle_stage` string	Current stage of the dispute lifecycle. Possible values: `INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, `ARBITRATION`. For more information, see Understand dispute lifecycle stages.	Use this value to determine your response to a dispute.
`evidences` array	Array of evidence documents.	Use this array to find the evidence requested for the dispute and share it using the Provide evidence endpoint.
`evidences.evidence_type` string	Type of evidence requested by PayPal. Possible values: `PROOF_OF_FULFILLMENT`, `PROOF_OF_REFUND`, `OTHER`, and so on.	Use this value to determine the evidence you need to provide.
`evidences.source` string	Source of the evidence.	If the value is `REQUESTED_FROM_SELLER`, you need to provide the evidence.
`seller_response_due_date` string	Due date and time by which you need to respond to the dispute.	Respond within this timeline to prevent the dispute from automatically closing in the customer’s favor.
`allowed_response_options` object	Allowed response options for the dispute. Response options: `make_offer.offer_types`: Types of applicable offers. Possible values: `REFUND`, `REFUND_WITH_RETURN`, `REFUND_WITH_REPLACEMENT`, `REPLACEMENT_WITHOUT_REFUND`. `accept_claim.accept_claim_types`: Types of applicable refunds. Possible values: `REFUND`, `REFUND_WITH_RETURN`, `PARTIAL_REFUND`, `REFUND_WITH_RETURN_SHIPMENT_LABEL`. `acknowledge_return_item.acknowledgement_types`: Types of applicable acknowledgements for the item returned by the buyer. Possible values: `ITEM_RECEIVED`, `ITEM_NOT_RECEIVED`, `DAMAGED`, `EMPTY_PACKAGE_OR_DIFFERENT`, `MISSING_ITEMS`.	Use this value to respond with one of the following options: Make an offer. Accept the claim. Acknowledge the returned item.
`links` array	Array of HATEOAS links that list the applicable actions for the dispute at its current stage.	Use these links to take further actions on the dispute.

For information on all response parameters, see API reference.

Respond to a dispute

After gathering dispute information, you can determine the appropriate response action using the following key parameters from the Show dispute details response:

Use the HATEOAS links to understand the actions available at any stage of the dispute case lifecycle.
Review the values of the dispute_life_cycle_stage and status parameters. Based on these values, the following table lists the possible response actions you can perform to ensure proper dispute handling:

Stage	Status	Description	Possible response actions
`INQUIRY`	`OPEN`	Dispute is created.	None
`INQUIRY`	`WAITING_FOR_SELLER_RESPONSE`	Waiting for merchant response.	Send message to other party Make offer to resolve dispute Accept claim Escalate dispute to claim Provide evidence
`INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`	`UNDER_REVIEW`	PayPal is reviewing the dispute.	Provide supporting information
`INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`	`WAITING_FOR_BUYER_RESPONSE`	Waiting for buyer response.	None
`CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`	`WAITING_FOR_SELLER_RESPONSE`	Waiting for merchant response.	Provide evidence Accept claim Make offer to resolve dispute Appeal dispute (available only for disputes resolved in buyer’s favor) Acknowledge returned item
`INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`	`RESOLVED`	Dispute is resolved.	None

Send message to other party

You can send a message to the other party during the inquiry stage to share information that helps resolve the dispute. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/send-message endpoint with the request parameter. Path parameter: {id} is the dispute_id returned in the List disputes response.

You can also attach documents and pictures to the message. To do this, you need to send a multipart request instead of a JSON one. For constraints and rules regarding documents, see Supported file types and sizes.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/send-message \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "message": "Shipment is in progress."
  }'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

Make offer to resolve dispute

You can make an offer to the buyer to resolve the dispute. To determine which offer types are available for a specific dispute, check the allowed_response_options.make_offer.offer_types parameter in the Show dispute details response. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/make-offer endpoint with the request parameters. Path parameter: {id} is the dispute_id returned in the List disputes response.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-ORC-10135512/make-offer \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "note": "Offer refund with replacement item.",
    "offer_amount": {
      "currency_code": "USD",
      "value": "10"
    },
    "offer_type": "REFUND_WITH_REPLACEMENT"
  }'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

Accept claim

You can accept liability for a dispute by accepting the claim. This closes the dispute in the buyer’s favor, and PayPal automatically refunds the buyer. To determine which refund types are available for a specific dispute, check the allowed_response_options.accept_claim.accept_claim_types parameter in the Show dispute details response. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/accept-claim endpoint with the request parameters. You can also include the accept claim reason or invoice ID if required. Path parameter: {id} is the dispute_id returned in the List disputes response.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/accept-claim \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "note": "Full refund to the customer."
  }'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

Provide evidence

You can provide evidence for a dispute to support your case. PayPal requests specific evidence based on the dispute reason. Check the following parameters in the Show dispute details response to determine what evidence to provide:

reason
evidences.evidence_type
evidences.source

Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/provide-evidence endpoint with the following parameters:

Parameter name	Action
`evidences.evidence_type` string	Set the evidence type as the value received in the Show dispute details response. For example, `PROOF_OF_FULFILLMENT`.
`evidences.documents` array	Provide the document details and attach the required evidence documents in the request. For constraints and rules regarding documents, see Supported file types and sizes.
`evidences.notes` string	Provide any additional notes regarding the evidence.
`evidences.evidence_info` object	Provide details such as `refund_ids` or `tracking_info` in this object based on the `evidence_type`. For example, provide refund ID for `PROOF_OF_REFUND` and tracking information for `PROOF_OF_FULFILLMENT`.

For more information on all request parameters, see API reference.

Path parameter: {id} is the dispute_id returned in the List disputes response.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-evidence \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'input={
    "evidences": [
      {
        "evidence_type": "PROOF_OF_FULFILLMENT",
        "evidence_info": {
          "tracking_info": [
            {
              "carrier_name": "FEDEX",
              "tracking_number": "122533485"
            }
          ]
        },
        "notes": "Test"
      }
    ]
  };type=application/json' \
  -F 'file1=@NewDoc.pdf;type=application/pdf'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

Escalate dispute to claim

If either party is unsatisfied with the other party’s response during the inquiry stage, they can escalate the dispute to a claim. The dispute then moves to the claim stage. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/escalate endpoint. Path parameter: {id} is the dispute_id returned in the List disputes response.

curl https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/escalate \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
  "note": "Escalating to PayPal claim for resolution."
  }'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

For more information, see API reference.

Provide supporting information

You can provide additional supporting information for a case under PayPal’s review to help with the review process. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/provide-supporting-info endpoint with the request parameter. Path parameter: {id} is the dispute_id returned in the List disputes response.

You can also provide documents and pictures by sending a multipart request instead of a JSON one. For constraints and rules regarding documents, see Supported file types and sizes.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-supporting-info \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "notes": "Additional supporting information"
  }'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

Appeal dispute

You can appeal a dispute that was resolved in the buyer’s favor. To determine if a dispute is eligible for appeal, check whether the HATEOAS link for appeal is present in the Show dispute details response. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/appeal endpoint with the following parameters:

Parameter name	Action
`evidences.evidence_type` string	Set the evidence type based on the evidence you are providing for your appeal. For example, `PROOF_OF_FULFILLMENT`.
`evidences.documents` array	Provide the document details and attach the required evidence documents in the request. For constraints and rules regarding documents, see Supported file types and sizes.
`evidences.notes` string	Provide any additional notes regarding the evidence.
`evidences.evidence_info` object	Provide details such as `refund_ids` or `tracking_info` in this object based on the `evidence_type`. For example, provide refund ID for `PROOF_OF_REFUND` and tracking information for `PROOF_OF_FULFILLMENT`.

For information on all request parameters, see API reference.

Path parameter: {id} is the dispute_id returned in the List disputes response.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/appeal \
  -H 'Content-Type: multipart/form-data' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -F 'input={
    "evidences": [
      {
        "evidence_type": "PROOF_OF_FULFILLMENT",
        "evidence_info": {
          "tracking_info": [
            {
              "carrier_name": "FEDEX",
              "tracking_number": "122533485"
            }
          ]
        },
        "notes": "Test"
      }
    ]
  };type=application/json' \
  -F 'file1=@NewDoc.pdf;type=application/pdf'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

Acknowledge returned item

For SNAD disputes with the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED reason, you can make an offer to resolve the dispute by offering a full refund in exchange for returning the item. After the buyer ships the returned item and reports it to PayPal, the acknowledge return item action becomes available. Use this endpoint to acknowledge receipt of the item. To determine which acknowledgements are available for a specific dispute, check the allowed_response_options.acknowledge_return_item.acknowledgement_types parameter in the Show dispute details response. Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/acknowledge-return-item endpoint. You can also include the note or acknowledgement type. Path parameter: {id} is the dispute_id for which you are acknowledging receipt of the returned item.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/acknowledge-return-item \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "note": "I have received the item back.",
    "acknowledgement_type": "ITEM_RECEIVED"
  }'

A successful call returns a 200 OK response and a HATEOAS link for the dispute.

For more information, see API reference.

Use webhooks to monitor dispute events

Webhook events are external events that your app does not know about unless it receives event notifications. For example, a new dispute raised or resolved is a webhook event. You can subscribe to such events and register a callback (listener) URL. When the event occurs, PayPal sends a notification to the registered callback URL. You can code your app to perform relevant actions based on the event notification it receives. To handle webhook events:

Review the list of webhook events for disputes and select the events for your app to subscribe.
Subscribe to the selected webhook events through one of the following means:
- PayPal developer account: Log in to your account, go to App details page > Features > Webhooks, and subscribe to webhook events.
- Webhooks management API.
In your server-side app code, define a webhook handler that:
- Listens to the webhook event.
- Confirms receipt of the webhook event to PayPal.
- Verifies the source of the event notification.
- Performs further actions based on event data.

For more information, see Webhooks overview and Webhooks integration guide.

Additional information

Article on disputes, claims, chargebacks, and bank reversals

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

Prerequisite

Understand dispute lifecycle stages

Gather dispute information

List disputes

Show dispute details

Respond to a dispute

Send message to other party

Make offer to resolve dispute

Accept claim

Provide evidence

Escalate dispute to claim

Provide supporting information

Appeal dispute

Acknowledge returned item

Use webhooks to monitor dispute events

Additional information

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

​Prerequisite

​Understand dispute lifecycle stages

​Gather dispute information

​List disputes

​Show dispute details

​Respond to a dispute

​Send message to other party

​Make offer to resolve dispute

​Accept claim

​Provide evidence

​Escalate dispute to claim

​Provide supporting information

​Appeal dispute

​Acknowledge returned item

​Use webhooks to monitor dispute events

​Additional information

Prerequisite

Understand dispute lifecycle stages

Gather dispute information

List disputes

Show dispute details

Respond to a dispute

Send message to other party

Make offer to resolve dispute

Accept claim

Provide evidence

Escalate dispute to claim

Provide supporting information

Appeal dispute

Acknowledge returned item

Use webhooks to monitor dispute events

Additional information