Skip to main content

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.

Required scope: inventory:write

Grant 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) and quantity (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_id and return_id are then not needed. A succeeded refund answers from the record; one Purple Dot definitely rejected is refused with purple_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 its refund_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_id is null).

Authentication: Requires a Bearer token. Requires the sales_orders.update permission.

Request​

Responses​

OK

Response Headers
    Content-Type