List disputes
GET {{base_url}}/v1/customer/disputes
Lists disputes with a summary set of details, which shows the disputeid, reason, status, disputestate, disputelifecyclestage, disputechannel, disputeamount, createtime and updatetime fields.
To filter the disputes in the response, specify one or more optional query parameters. To limit the number of disputes in the response, specify the pagesize query parameter.
To list multiple disputes, set these query parameters in the request:
pagesize=2starttimeinstead ofdisputedtransactionid
If the response contains more than two disputes, it lists two disputes and includes a HATEOAS link to the next page of results.
Request Params
| Key | Datatype | Required | Description |
|---|---|---|---|
start_time | string | Filters the disputes in the response by a creation date and time. The start time must be within the last 180 days. Value is in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.<br/><br/>You can specify either but not both the start_time and disputed_transaction_id query parameters. | |
disputed_transaction_id | string | Filters the disputes in the response by a transaction, by ID.<br/><br/>You can specify either but not both the start_time and disputed_transaction_id query parameter. | |
page_size | number | Limits the number of disputes in the response to this value. | |
next_page_token | null | The token that describes the next page of results to fetch. The <a href="https://developer.paypal.com/api/customer-disputes/v1/#disputes_list">list disputes</a> call returns this token in the HATEOAS links in the response. | |
dispute_state | string | Filters the disputes in the response by a state. Separate multiple values with a comma (,). When you specify more than one dispute_state, the response lists disputes that belong to any of the specified dispute_state. | |
update_time_before | string | The date and time when the dispute was last updated, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ. update_time_before must be within the last 180 days and the default is the current time. | |
update_time_after | string | The date and time when the dispute was last updated, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ. update_time_after must be within the last 180 days and the default is the maximum time (180 days) supported. |
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string | The Content-Type header field is used to specify the nature of the data in the body of an entity. PayPal REST APIs support application/json. | |
PayPal-Request-Id | string | The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. | |
PayPal-Client-Metadata-Id | string | Optional. Verifies that the payment originates from a valid, user-consented device and application. Reduces fraud and decreases declines. Transactions that do not include a client metadata ID are not eligible for PayPal Seller Protection. | |
PayPal-Partner-Attribution-Id | string | Optional. Identifies the caller as a PayPal partner. To receive revenue attribution, specify a unique build notation (BN) code. BN codes provide tracking on all transactions that originate or are associated with a particular partner. To find your BN code, see Code and Credential Reference. | |
PayPal-Auth-Assertion | string | An API client-provided JSON Web Token (JWT) assertion that identifies the merchant. To use this header, you must get consent to act on behalf of a merchant. | |
Prefer | string | The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul> | |
Prefer | string | The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul> |
RESPONSES
status: OK
{"items":[{"dispute_id":"PP-D-61394","create_time":"2022-02-02T03:23:10.000Z","update_time":"2022-02-02T03:28:07.000Z","reason":"MERCHANDISE_OR_SERVICE_NOT_RECEIVED","status":"WAITING_FOR_SELLER_RESPONSE","dispute_state":"REQUIRED_ACTION","dispute_amount":{"currency_code":"USD","value":"100.00"},"dispute_life_cycle_stage":"INQUIRY","links":[{"href":"https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-61394","rel":"self","method":"GET"}]}],"links":[{"href":"https://api.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=8E3322494D591061V","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=8E3322494D591061V","rel":"first","method":"GET"}]}