POST
/
v1
/
refunds
curl --location --request POST 'https://api.stateset.com/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "order_id": "order_123456",
    "type": "partial",
    "reason": "product_damaged",
    "reason_details": "Item arrived with scratches on the surface",
    "items": [
        {
            "line_item_id": "li_abc123",
            "quantity": 1,
            "restock": false
        }
    ],
    "amounts": {
        "subtotal": 4999,
        "tax": 450,
        "shipping": 0,
        "total": 5449
    },
    "payment_method": {
        "type": "original_payment",
        "payment_id": "pay_xyz789"
    },
    "processing": {
        "auto_approve": true,
        "notify_customer": true,
        "process_immediately": true
    }
}'

{
  "id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "refund",
  "order_id": "order_123456",
  "customer_id": "cust_abc123",
  "type": "partial",
  "status": "processing",
  "reason": "product_damaged",
  "reason_details": "Item arrived with scratches on the surface",
  "items": [
    {
      "line_item_id": "li_abc123",
      "product_id": "prod_123",
      "product_name": "Wireless Headphones",
      "quantity": 1,
      "refund_amount": 4999,
      "restock": false,
      "restock_status": "not_restocking"
    }
  ],
  "amounts": {
    "subtotal": 4999,
    "tax": 450,
    "shipping": 0,
    "adjustment": 0,
    "total": 5449,
    "currency": "USD"
  },
  "payment_method": {
    "type": "original_payment",
    "payment_id": "pay_xyz789",
    "last4": "4242",
    "brand": "visa"
  },
  "payment_status": "pending",
  "transaction_id": null,
  "processing": {
    "auto_approved": true,
    "approved_at": "2024-01-20T13:30:00Z",
    "approved_by": "system"
  },
  "shipping": {
    "return_required": false,
    "return_label_id": null
  },
  "timeline": [
    {
      "status": "created",
      "timestamp": "2024-01-20T13:30:00Z",
      "actor": "customer"
    },
    {
      "status": "approved",
      "timestamp": "2024-01-20T13:30:01Z",
      "actor": "system"
    },
    {
      "status": "processing",
      "timestamp": "2024-01-20T13:30:02Z",
      "actor": "system"
    }
  ],
  "created_at": "2024-01-20T13:30:00Z",
  "updated_at": "2024-01-20T13:30:02Z",
  "estimated_completion": "2024-01-23T13:30:00Z",
  "notes": null,
  "metadata": {}
}
This endpoint creates a refund request that can process partial or full refunds. It handles payment reversals, inventory adjustments, and customer notifications.

​
Authentication

This endpoint requires a valid API key with refunds:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
order_id
string
required
Original order ID to refund
​
type
string
required
Refund type: “full”, “partial”, “item_return”, “shipping”, “tax_only”
​
reason
string
required
Refund reason code
​
reason_details
string
Detailed explanation of refund reason
​
items
array
Items to refund (required for partial/item refunds)
​
amounts
object
required
Refund amounts breakdown
​
payment_method
object
Refund payment method
​
shipping
object
Return shipping details
​
processing
object
Processing options
​
notes
string
Internal notes about the refund
​
metadata
object
Additional custom fields

​
Response

Returns the created refund object. 
curl --location --request POST 'https://api.stateset.com/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "order_id": "order_123456",
    "type": "partial",
    "reason": "product_damaged",
    "reason_details": "Item arrived with scratches on the surface",
    "items": [
        {
            "line_item_id": "li_abc123",
            "quantity": 1,
            "restock": false
        }
    ],
    "amounts": {
        "subtotal": 4999,
        "tax": 450,
        "shipping": 0,
        "total": 5449
    },
    "payment_method": {
        "type": "original_payment",
        "payment_id": "pay_xyz789"
    },
    "processing": {
        "auto_approve": true,
        "notify_customer": true,
        "process_immediately": true
    }
}'

{
  "id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "refund",
  "order_id": "order_123456",
  "customer_id": "cust_abc123",
  "type": "partial",
  "status": "processing",
  "reason": "product_damaged",
  "reason_details": "Item arrived with scratches on the surface",
  "items": [
    {
      "line_item_id": "li_abc123",
      "product_id": "prod_123",
      "product_name": "Wireless Headphones",
      "quantity": 1,
      "refund_amount": 4999,
      "restock": false,
      "restock_status": "not_restocking"
    }
  ],
  "amounts": {
    "subtotal": 4999,
    "tax": 450,
    "shipping": 0,
    "adjustment": 0,
    "total": 5449,
    "currency": "USD"
  },
  "payment_method": {
    "type": "original_payment",
    "payment_id": "pay_xyz789",
    "last4": "4242",
    "brand": "visa"
  },
  "payment_status": "pending",
  "transaction_id": null,
  "processing": {
    "auto_approved": true,
    "approved_at": "2024-01-20T13:30:00Z",
    "approved_by": "system"
  },
  "shipping": {
    "return_required": false,
    "return_label_id": null
  },
  "timeline": [
    {
      "status": "created",
      "timestamp": "2024-01-20T13:30:00Z",
      "actor": "customer"
    },
    {
      "status": "approved",
      "timestamp": "2024-01-20T13:30:01Z",
      "actor": "system"
    },
    {
      "status": "processing",
      "timestamp": "2024-01-20T13:30:02Z",
      "actor": "system"
    }
  ],
  "created_at": "2024-01-20T13:30:00Z",
  "updated_at": "2024-01-20T13:30:02Z",
  "estimated_completion": "2024-01-23T13:30:00Z",
  "notes": null,
  "metadata": {}
}