Create Refund
POST/api/purple-dot/refunds
Refunds lines (and optionally shipping) of an exported Purple Dot order through Purple Dot. Purple Dot is sent one line_items entry of quantity 1 per unit, and shipping: true for shipping; a bundle is refunded in whole purchased bundles. The refund is stored as unconfirmed (holding its units) before Purple Dot is called, sent in one attempt, and on success gets a note on the sales order.
inventory:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Idempotency: an existing operation is resolved before any quantity check. Re-sending the same refund (same key, lines and shipping) returns the stored refund without calling Purple Dot again; after a failure it re-sends the same operation under the same id. A different refund under the same key is refused with refund_conflict and nothing is sent. The key is rma-{return_id} for a return, otherwise so-{sales_order_id}-{request_id}.
A returned unit is refunded once: refunds for a return (manual or the Auto receipt refunds) are counted against that return's units.
Body fields:
- sales_order_id (integer, required)
- return_id (integer, optional): the RMA being refunded; at most its returned units not yet refunded for it.
- request_id (UUID, required without return_id): generated once by the client for this refund and re-sent unchanged on every retry, so a retry after a timeout can never refund twice.
- line_items (array, required, may be empty when only shipping is refunded):
sales_order_line_id(integer, required, distinct; a bundle's line from the preview) andquantity(integer, 0–100000; 0 is skipped; purchased bundles for a bundle). - include_shipping (boolean, optional, default false): refused once shipping was refunded.
- refund_id (integer, optional): retry an unconfirmed refund (from the preview's
pending_refunds) exactly as it was first sent, under its original key;line_items,request_idandreturn_idare then not needed. A succeeded refund answers from the record; one Purple Dot definitely rejected is refused withpurple_dot_error(start a new refund).
Response: the stored refund; amount / currency are Purple Dot's data.refunded.amount / .currency; uncertain is true for a failed refund Purple Dot never confirmed.
Errors (all 422 with message, error_code and the stored refund_id when Purple Dot was called):
not_purple_dot: Purple Dot did not export the order, or refunds are off for the connection.invalid_lines: a line is not on the order (or is a bundle component), asks for more than is still refundable on the order or the return, or shipping was already refunded.refund_conflict: Purple Dot already has a refund with this id and a different payload (HTTP 409), or the key was already used for a different refund. SKU.io does not retry with a new id.refund_uncertain: Purple Dot did not confirm the refund (timeout, lost connection, 5xx), so it may or may not have gone through. Retry with the same body (or itsrefund_id); a different body under the same key is refused with this code. Uncertainty is sticky: a later rejection (401, 4xx) of a retry keeps the refund unconfirmed and its units held until Purple Dot confirms it.invalid_token: Purple Dot rejected the access token.purple_dot_error: any other Purple Dot error, or another refund for the same sales order is still being sent (wait, check the order, then retry;refund_idis null).
Authentication: Requires a Bearer token. Requires the sales_orders.update permission.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.