> ## 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.

# Create Refund

> Create a refund for an order or specific items

<Note>
  This endpoint creates a refund request that can process partial or full refunds. It handles payment reversals, inventory adjustments, and customer notifications.
</Note>

## Authentication

This endpoint requires a valid API key with `refunds:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="order_id" type="string" required>
  Original order ID to refund
</ParamField>

<ParamField body="type" type="string" required>
  Refund type: "full", "partial", "item\_return", "shipping", "tax\_only"
</ParamField>

<ParamField body="reason" type="string" required>
  Refund reason code
</ParamField>

<ParamField body="reason_details" type="string">
  Detailed explanation of refund reason
</ParamField>

<ParamField body="items" type="array">
  Items to refund (required for partial/item refunds)

  <Expandable title="Item properties">
    <ParamField body="line_item_id" type="string" required>
      Original order line item ID
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity to refund
    </ParamField>

    <ParamField body="amount" type="integer">
      Override refund amount in cents
    </ParamField>

    <ParamField body="restock" type="boolean">
      Whether to restock this item
    </ParamField>

    <ParamField body="restock_location_id" type="string">
      Location to restock to
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="amounts" type="object" required>
  Refund amounts breakdown

  <Expandable title="Amount properties">
    <ParamField body="subtotal" type="integer" required>
      Items subtotal to refund in cents
    </ParamField>

    <ParamField body="tax" type="integer">
      Tax amount to refund in cents
    </ParamField>

    <ParamField body="shipping" type="integer">
      Shipping amount to refund in cents
    </ParamField>

    <ParamField body="adjustment" type="integer">
      Manual adjustment amount (positive or negative)
    </ParamField>

    <ParamField body="total" type="integer" required>
      Total refund amount in cents
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payment_method" type="object">
  Refund payment method

  <Expandable title="Payment method properties">
    <ParamField body="type" type="string">
      Refund method: "original\_payment", "store\_credit", "gift\_card", "check", "manual"
    </ParamField>

    <ParamField body="payment_id" type="string">
      Original payment ID to refund to
    </ParamField>

    <ParamField body="store_credit_id" type="string">
      Store credit account ID
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping" type="object">
  Return shipping details

  <Expandable title="Shipping properties">
    <ParamField body="return_label_required" type="boolean">
      Whether return shipping label is needed
    </ParamField>

    <ParamField body="carrier" type="string">
      Return carrier
    </ParamField>

    <ParamField body="service" type="string">
      Return service type
    </ParamField>

    <ParamField body="prepaid_label_id" type="string">
      Pre-generated return label ID
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="processing" type="object">
  Processing options

  <Expandable title="Processing properties">
    <ParamField body="auto_approve" type="boolean">
      Auto-approve if within policy
    </ParamField>

    <ParamField body="notify_customer" type="boolean">
      Send customer notification
    </ParamField>

    <ParamField body="process_immediately" type="boolean">
      Process payment refund immediately
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="notes" type="string">
  Internal notes about the refund
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created refund object.

<RequestExample>
  ```bash cURL theme={null}
  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
      }
  }'
  ```

  ```javascript Node.js theme={null}
  const refund = await stateset.refunds.create({
    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
    }
  });
  ```

  ```python Python theme={null}
  refund = stateset.refunds.create(
    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
    }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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": {}
  }
  ```
</ResponseExample>