Customer Disputes Frequently Asked Questions (FAQ)

This document answers these common questions from developers:

What is the Customer Disputes API?

The Customer Disputes API is a REST API that you use to list cases, see dispute details, provide evidence, accept claims, and appeal cases for your PayPal account.

Who can create disputes with PayPal?

Customers can create and file disputes with PayPal.

How can a customer file a dispute for a PayPal transaction?

Customers have three ways of filing disputes. For details, see Disputes, claims, chargebacks, and bank reversals.

What is the purpose of the Customer Disputes API for merchants?

The Customer Disputes API is real time, robust, and supports RESTful-based integrations to search, list, and respond to disputes. Merchants can use the API to list all customer disputes with PayPal, show details for a dispute, and respond to a dispute. Merchants can use the API to build contextual dispute resolution experiences.

Are additional fees required to integrate with the Customer Disputes API?

No additional fees are required to integrate with the API as a PayPal customer.

Does the API handle multiple currencies?

Yes, the API can handle all currencies in countries where PayPal operates.

Who arbitrates when a customer and merchant cannot reach agreement?

In these situations, PayPal intervenes, adjudicates the case, and applies appropriate seller protection policies. The decision-making process does not change with the Customer Disputes API integration and is consistent across PayPal.

Do merchants need separate logins?

No. However, you need a developer account to integrate with PayPal public APIs.

Can a merchant see customer-submitted evidence?

No. For legal and privacy reasons, a merchant cannot see this information.

Is the dispute history retained and accessible?

Yes. The PayPal back end maintains this information. However, the merchant cannot access it. If a merchant needs dispute history, the merchant can pull API responses into their systems.

When will the Customer Disputes API be available for all PayPal merchants?

The Customer Disputes API is available to all merchants as of May 3, 2018.

Is the dispute phase supported?

Yes. The Customer Disputes API supports both dispute and claim phases.

How does a merchant know the outcome of a dispute?

The outcome of a resolved dispute is available as the value of the dispute_outcome object.

The following table maps the dispute_outcome value to a win or a loss for a merchant.

Value Win or loss
NONE Neither. A dispute was created for the same transaction ID, and the previous dispute was closed without any decision.
Empty value Neither. The dispute is not resolved yet.

Can the dispute lifecycle move to a previous stage?

Yes. In most cases, the value of dispute_lifecycle_stage moves from INQUIRY to CHARGEBACK to PRE_ARBITRATION to ARBITRATION. The following scenarios cause the dispute_lifecycle_stage to move to a previous stage:

  • When a customer files an external case with their bank or credit card issuer on a dispute, the dispute is updated with a new lifecycle stage.
  • When a customer changes the dispute_reason, the dispute is updated with a new lifecycle stage. For example, if the dispute_reason is MERCHANDISE_OR_SERVICE_NOT_RECEIVED and the customer later receives a broken item, the customer can change the dispute_reason to MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. In that case, the lifecycle stage is reset to CHARGEBACK.

Is it possible to miss some webhook notifications?

Yes. You must configure a webhook listener and subscribe to all Customer Disputes webhook events. You can subscribe to these dispute-related events:


If you do not subscribe to an event, you do not receive notifications for that event.

For more information about how to configure a webhook listener and subscribe to Customer Disputes webhooks, see Customer Disputes and Webhooks.