get https://{subdomain}.myshoplaza.com/openapi/2024-07/shoplazza-payment/disputes
Requires
read_financeaccess scope.
List Disputes
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
Query Parameters
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
cursor | string | No | "abc123" | Cursor for pagination, use the cursor from the response for pagination. |
limit | 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
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
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Description | Example |
|---|---|---|---|
code | string | The error code indicating the type of issue. | InvalidParameter |
message | string | A detailed message describing the error. | wrong cursor |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure (e.g., missing required fields or incorrect data types). | Bad Request |
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized |