🔒
Requires read_finance access 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

📘
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.
`page_size`	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

📘
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

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