This endpoint returns a paginated list of refunds. You can filter by status, date range, customer, and more.
Authentication
This endpoint requires a valid API key with refunds:read permissions.
Authorization: Bearer YOUR_API_KEY
Query Parameters
Number of refunds to return (1-100)
Number of refunds to skip
Filter by status: “pending”, “approved”, “processing”, “completed”, “rejected”, “cancelled”
Filter by type: “full”, “partial”, “item_return”, “shipping”, “tax_only”
Filter refunds created after date (ISO 8601)
Filter refunds created before date (ISO 8601)
Filter by refund reason code
sort_by
string
default:"created_at"
Sort by field: “created_at”, “updated_at”, “amount”, “status”
Sort order: “asc” or “desc”
Response
Returns a paginated list of refund objects.
curl --location 'https://api.stateset.com/v1/refunds?status=processing&limit=20' \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"object": "list",
"data": [
{
"id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "refund",
"order_id": "order_123456",
"customer_id": "cust_abc123",
"type": "partial",
"status": "processing",
"reason": "product_damaged",
"amounts": {
"total": 5449,
"currency": "USD"
},
"created_at": "2024-06-20T13:30:00Z",
"estimated_completion": "2024-06-23T13:30:00Z"
},
{
"id": "refund_1234f083-bb2d-54d6-bg6d-1b0e3gd75f41",
"object": "refund",
"order_id": "order_234567",
"customer_id": "cust_def456",
"type": "full",
"status": "processing",
"reason": "order_cancelled",
"amounts": {
"total": 15999,
"currency": "USD"
},
"created_at": "2024-06-20T12:00:00Z",
"estimated_completion": "2024-06-23T12:00:00Z"
}
],
"has_more": true,
"total_count": 156,
"url": "/v1/refunds",
"summary": {
"total_amount": 847532,
"average_processing_time": 72,
"status_breakdown": {
"pending": 12,
"approved": 8,
"processing": 45,
"completed": 87,
"rejected": 3,
"cancelled": 1
}
}
}
