get https://{subdomain}.myshoplaza.com/openapi/2024-07/shoplazza-payment/refunds
Requires
read_financeaccess scope.
The List Refunds API retrieves a list of refunds created by the user. The refunds are returned in a sorted order, with the most recently initiated refunds appearing first.
This API is especially useful for:
- Tracking the status of initiated refunds.
- Filtering refunds by initiation timeline and their current status.
- Managing paginated refund records efficiently using a cursor-based approach.
Request Parameters
Public Request Parameters
Query Parameters
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
cursor | string | No | abc123 | Starting ID for pagination. Use the cursor from the response for subsequent pages. |
limit | int32 | No | 10 | A limit on the number of objects to be returned. Range: 1-100. Default is 10. |
status | string | No | succeeded | Filter option: Refund status: succeeded: The refund was successfully processed. failed: The refund attempt failed, and no funds were returned. processing: The refund is currently being processed, with final results pending. |
created_at_min | string | No | 2024-04-01T00:00:00Z | Filter option: Refund initiation start time (in UNIX timestamp or ISO-8601 format). |
created_at_max | string | No | 2024-04-30T23:59:59Z | Filter option: Refund initiation end time (in UNIX timestamp or ISO-8601 format). |
Response Explanation
Public Response Parameters
Successful Response
| Field | Type | Example | Description |
|---|---|---|---|
code | string | "Success" | Status code for the request. |
message | string | "Request completed" | Additional message about the response. |
data | object | Contains the refund list, pagination cursor, and metadata. | |
data.has_more | boolean | true | Indicates whether more pages of refunds are available. |
data.list | array | List of refund objects. | |
data.cursor | string | "abc123" | Cursor for fetching the next page of results. |
data.list[].id | string | "123456" | Unique identifier for the refund. |
data.list[].store_id | string | "store123" | Store ID associated with the refund. |
data.list[].balance_currency | string | "USD" | Currency used for the balance. |
data.list[].transaction_order_id | string | "trans123" | ID of the transaction order associated with the refund. |
data.list[].status | string | "succeeded" | Status of the refund: succeeded: Refund successfully processed. failed: Refund failed. processing: Refund is pending processing. |
data.list[].amount | string | "50.00" | Refund amount. |
data.list[].currency | string | "USD" | Currency code of the refund (e.g., USD). |
data.list[].original_order_amount | string | "100.00" | Original order amount prior to the refund. |
data.list[].created_at | string | "2024-04-28T06:50:19Z" | Refund creation timestamp (ISO-8601 format). |
data.list[].completed_at | string | "2024-04-28T06:52:36Z" | Timestamp indicating when the refund was completed (ISO-8601 format). |
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 | |
| 500 | InvalidParameter | cursor is not invalid | "rpc error: code = Code(400) desc = wrong cursor" |