Create Refund

Create a refund for an order or specific items

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)

Show Item properties

line_item_id · string · required

Original order line item ID

quantity · integer · required

Quantity to refund

amount · integer

Override refund amount in cents

restock · boolean

Whether to restock this item

restock_location_id · string

Location to restock to

amounts · object · required

Refund amounts breakdown

Show Amount properties

subtotal · integer · required

Items subtotal to refund in cents

tax · integer

Tax amount to refund in cents

shipping · integer

Shipping amount to refund in cents

adjustment · integer

Manual adjustment amount (positive or negative)

total · integer · required

Total refund amount in cents

payment_method · object

Refund payment method

Show Payment method properties

type · string

Refund method: “original_payment”, “store_credit”, “gift_card”, “check”, “manual”

payment_id · string

Original payment ID to refund to

store_credit_id · string

Store credit account ID

shipping · object

Return shipping details

Show Shipping properties

return_label_required · boolean

Whether return shipping label is needed

carrier · string

Return carrier

service · string

Return service type

prepaid_label_id · string

Pre-generated return label ID

processing · object

Processing options

Show Processing properties

auto_approve · boolean

Auto-approve if within policy

notify_customer · boolean

Send customer notification

process_immediately · boolean

Process payment refund immediately

notes · string

Internal notes about the refund

metadata · object

Additional custom fields

Response

Returns the created refund object.

cURL

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
    }
}'

Response

{
  "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": {}
}