🔒
Requires read_finance access scope.

The List Disputes API retrieves a list of dispute objects sorted in descending order by their creation date. The most recently created dispute appears first.

This API is especially useful for:

Monitoring the status and details of multiple dispute cases.
Filtering disputes based on their creation timeline and status.
Paginating dispute records using cursors for better management.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Field	Type	Required	Example	Description
`cursor`	string	No	`"abc123"`	Cursor for pagination, use the cursor from the response for pagination.
`page_size`	int32	No	`10`	A limit on the number of objects to be returned. Range: 1–100. Default is 10.
`status`	string	No	`"won"`	Filter option for dispute status. Accepted values: `lost`, `won`, `warning_closed`, `needs_response`, `under_review`, `warning_under_review`, `warning_needs_response`. Status Values `lost`: The dispute was resolved against the merchant, and the funds were not recovered. `won`: The dispute resolved in favor of the merchant, and the funds were retained or recovered. `warning_closed`: The dispute case was closed following a warning; no further action is required. `needs_response`: The dispute requires a response or evidence from the merchant to proceed. `under_review`: The dispute is currently under review by the payment processor or financial institution. `warning_under_review`: The dispute received a warning and is under review; further action may be needed. `warning_needs_response`: The dispute has a warning and requires a response from the merchant to avoid escalation.
`created_at_min`	string	No	`"1714104673"`	Filter option: dispute creation start time (Unix timestamp).
`created_at_max`	string	No	`"1714105273"`	Filter option: dispute creation end time (Unix timestamp).

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Field	Type	Example	Description
`code`	string	`"Success"`	Response code indicating the status of the API call.
`message`	string	`"Success"`	Response message providing additional information.
`data`	object		Contains the list of dispute objects and pagination details.
`data.has_more`	boolean	`true`	Indicates if more results are available beyond the current list.
`data.cursor`	string	`"abc123"`	Cursor for pagination to retrieve the next set of results.
`data.list`	array		List of dispute objects.
`data.list[].id`	string	`"123456"`	Unique identifier for the dispute.
`data.list[].transaction_order_id`	string	`"order_7890"`	Transaction order ID related to the dispute.
`data.list[].original_order_id`	string	`"order_1234"`	Original order ID related to the transaction.
`data.list[].store_id`	string	`"store_5678"`	Unique identifier for the store.
`data.list[].currency`	string	`"USD"`	Currency code of the dispute amount.
`data.list[].created_at`	string	`"2024-04-28T12:34:56Z"`	Creation time of the dispute in ISO 8601 format.
`data.list[].updated_at`	string	`"2024-04-29T15:20:10Z"`	Last updated time of the dispute in ISO 8601 format.
`data.list[].expiration_time`	string	`"2024-05-05T00:00:00Z"`	Expiration time for responding to the dispute.
`data.list[].dispute_reason`	string	`"Fraudulent"`	Reason provided for the dispute.
`data.list[].original_order_amount`	string	`"100.00"`	Total amount of the original order.
`data.list[].dispute_amount`	string	`"50.00"`	Amount of the dispute.
`data.list[].status`	string	`"won"`	Current status of the dispute. Possible values: `won`, `lost`, `under_review`, etc.
`data.list[].fee`	string	`"10.00"`	Fees associated with the dispute.
`data.list[].fee_currency`	string	`"USD"`	Currency of the associated fee.

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

API Structure Overview