# /refund

#### `POST /refund`

#### Create a refund for an order.

Request:

* `id` (string) - Required. Idempotency key. Reusing the same `id` and `order` with the same payload returns the existing refund result; sending a different payload for the same `id` and `order` returns 409 Conflict.
* `order` (string) - Required. External order ID (e.g. Shopify order ID).

You must provide either a line-item refund or an appeasement refund, but not both.

For a **line-item refund**, provide at least one of:

* `line_items` (array) - Optional. The line items to refund. Each element must have:
  * `id` (string) - Required. External line item ID (e.g. Shopify line item ID).
  * `quantity` (number) - Required. Must be 1.
* `shipping` (boolean) - Optional. Refund shipping for the order. Shipping can only be refunded once per order.

For an **appeasement refund**, provide:

* `amount` (string) - Required. The amount to refund (must be a decimal string).
* `currency` (string) - Required. Must match the order's presentment currency.

Body:

* `id` - The idempotency key from the request
* `order` - The external order ID from the request
* `refunded`
  * `amount` - The refunded amount as a string
  * `currency` - The refunded amount currency

Errors:

* 400 - INVALID\_REFUND\_REQUEST: Mixed line-item and appeasement payload; missing or invalid amount/currency for appeasement; or currency does not match the order.
* 400 - INVALID\_LINE\_ITEMS: The line items array contains invalid entries (e.g. missing id or quantity, or quantity is not 1).
* 400 - CURRENCY\_MISMATCH: Appeasement refund currency does not match the order's presentment currency.
* 400 - SHIPPING\_ALREADY\_REFUNDED: Line-item refund with shipping requested but shipping was already refunded for this order.
* 400 - NOT\_ENOUGH\_ITEMS\_LEFT\_TO\_REFUND: Requested line-item quantities exceed the remaining refundable quantity.
* 404 - UNKNOWN\_ORDER: Order not found or not for this store.
* 404 - UNKNOWN\_LINE\_ITEMS: One or more line item ids are not on the order.
* 409 - IDEMPOTENT\_REQUEST\_PAYLOAD\_MISMATCH: Same id and order were used with a different payload.
* 500 - REFUND\_FAILED: Order has mixed checkout/preorder line items, or the payment refund failed.
* 501 - Orders that span multiple pre-orders are not supported.

Examples:

{% code overflow="wrap" %}

```bash
curl --request POST \
     --url 'https://www.purpledotprice.com/admin/api/v1/refund' \
     --header 'Content-Type: application/json' \
     --header 'X-Purple-Dot-Access-Token: <access_token>' \
     --data '{"id": "refund-001", "order": "gid://shopify/Order/123", "line_items": [{"id": "gid://shopify/LineItem/456", "quantity": 1}], "shipping": false}'
```

{% endcode %}

{% code overflow="wrap" %}

```bash
curl --request POST \
     --url 'https://www.purpledotprice.com/admin/api/v1/refund' \
     --header 'Content-Type: application/json' \
     --header 'X-Purple-Dot-Access-Token: <access_token>' \
     --data '{"id": "refund-002", "order": "gid://shopify/Order/123", "amount": "10.00", "currency": "USD"}'
```

{% endcode %}

{% code overflow="wrap" %}

```json
{
  "meta": {
    "result": "success"
  },
  "data": {
    "id": "refund-001",
    "order": "gid://shopify/Order/123",
    "refunded": {
      "amount": "42.00",
      "currency": "USD"
    }
  }
}
```

{% endcode %}