# /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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/refund.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.