Skip to main content
GET
/
v1
/
refunds
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
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.stateset.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
limit
integer
default:"10"
Number of refunds to return (1-100)
​
offset
integer
default:"0"
Number of refunds to skip
​
status
string
Filter by status: “pending”, “approved”, “processing”, “completed”, “rejected”, “cancelled”
​
type
string
Filter by type: “full”, “partial”, “item_return”, “shipping”, “tax_only”
​
order_id
string
Filter by specific order
​
customer_id
string
Filter by customer
​
created_after
string
Filter refunds created after date (ISO 8601)
​
created_before
string
Filter refunds created before date (ISO 8601)
​
reason
string
Filter by refund reason code
​
sort_by
string
default:"created_at"
Sort by field: “created_at”, “updated_at”, “amount”, “status”
​
sort_order
string
default:"desc"
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
    }
  }
}