> 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

## Create a refund

> Creates a refund for an order, paid back to the shopper against the underlying Purple Dot pre-order payments. Use either a line-item refund (\`line\_items\` and/or \`shipping\`) or a custom amount refund (\`amount\` and \`currency\`), not both. Line-item refunds are supported only for Shopify stores.

```json
{"openapi":"3.1.0","info":{"title":"Purple Dot Private API","version":"v1"},"tags":[{"name":"/refund"}],"servers":[{"url":"https://www.purpledotprice.com/admin/api/v1","description":"Production"}],"security":[{"accessToken":[]}],"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"X-Purple-Dot-Access-Token","description":"Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."}},"schemas":{"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"errorData":{"type":"object","additionalProperties":{},"description":"Structured detail about the error."}},"required":["error","errorData"]},"data":{"type":"object","properties":{}}},"required":["meta","data"]}}},"paths":{"/refund":{"post":{"tags":["/refund"],"summary":"Create a refund","description":"Creates a refund for an order, paid back to the shopper against the underlying Purple Dot pre-order payments. Use either a line-item refund (`line_items` and/or `shipping`) or a custom amount refund (`amount` and `currency`), not both. Line-item refunds are supported only for Shopify stores.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Idempotency key, unique for each distinct refund (a refund document number, return ID or support ticket ID). To retry after a timeout, reuse the same `id`, `order` and payload: a prior success returns the same result and does not refund the shopper twice. The same `id` and `order` with a different payload returns `409`. Use a new `id` for each separate refund, even on the same order."},"order":{"type":"string","description":"External order ID to refund. On Shopify, the Shopify order ID. On other platforms, the Purple Dot fulfillment order UUID from `GET /fulfillment-orders`."},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"External line item ID (for example, the Shopify line item ID)."},"quantity":{"type":"number","enum":[1],"description":"Must be `1`."}},"required":["id","quantity"]},"description":"Line-item refunds only. The line items to refund."},"shipping":{"type":"boolean","default":false,"description":"Line-item refunds only. Refunds shipping for the order. Shipping can be refunded only once per order."},"amount":{"type":"string","description":"Custom amount refunds only. Amount to refund, as a decimal string."},"currency":{"type":"string","description":"Custom amount refunds only. Must match the order's presentment currency."}},"required":["id","order"]}}}},"responses":{"200":{"description":"The refund.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"result":{"type":"string","enum":["success"]}},"required":["result"]},"data":{"type":"object","properties":{"id":{"type":"string","description":"Idempotency key from the request."},"order":{"type":"string","description":"External order ID from the request."},"refunded":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]}},"required":["id","order","refunded"]}},"required":["meta","data"]}}}},"400":{"description":"Missing access token. One of `INVALID_REFUND_REQUEST`, `INVALID_LINE_ITEMS`, `CURRENCY_MISMATCH`, `SHIPPING_ALREADY_REFUNDED` or `NOT_ENOUGH_ITEMS_LEFT_TO_REFUND`.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Access token not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}},"404":{"description":"One of `UNKNOWN_ORDER` or `UNKNOWN_LINE_ITEMS`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`IDEMPOTENT_REQUEST_PAYLOAD_MISMATCH`: the same `id` and `order` were used with a different payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The refund could not be completed, including orders spanning multiple pre-orders, mixed checkout and pre-order line items, or payment refund failures. `meta.error` contains a generic error message; `meta.errorData` may contain request details, but no refund failure code is exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
