> For the complete documentation index, see [llms.txt](https://docs.getpurpledot.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/refund.md).

# /refund

#### `POST /refund`

#### Create a refund for an order.

Refunds money to the shopper against the underlying Purple Dot preorder payments. You must provide either a **line-item refund** (only supported for Shopify stores) or an **custom amount refund**, but not both.

**Request Body**:

* `id` (string) - Required. Idempotency key. 
  * Must be unique for each distinct refund. This could be a refund document number, return ID, or support case/ticket ID tied to that specific refund.
  * Reuse the **same** `id`, `order`, and payload when retrying after a timeout or network error. A successful prior attempt returns the same result and will not refund the shopper twice. Sending a different payload for the same `id` and `order` returns 409 Conflict.
  * Use a **new** `id` for each separate refund, even on the same order.
  * Do **not** generate a new random ID on every HTTP retry.
* `order` (string) - Required. External order ID to refund.
  * On Shopify stores, use the **Shopify order ID**. 
  * For other e-commerce platforms, use the Purple Dot **fulfillment order UUID**. Look up the fulfillment order via [`GET /fulfillment-orders`](https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/fulfillment-orders).

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.

{% hint style="info" %}
Note: line-item refunds are currently only supported for Shopify stores.
{% endhint %}

For a **custom amount** **refund**, provide:

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

**Response Data**:

* `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 %}