Get Refund Preview
GET/api/purple-dot/refunds/preview
Returns what can be refunded through Purple Dot on an exported order: each Purple Dot line with its unit price, the quantity on the given return (received, or expected while nothing is received, less what was already refunded for that return) and the most that can still be refunded, plus the shipping still refundable (0 once shipping was refunded), currency and the connection's refund mode (ask, auto, off). A bundle is ONE line (is_bundle: true) keyed by its first component line and counted in purchased bundles; its unit price is the bundle's price.
inventory:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
pending_refunds lists every refund of the order Purple Dot never confirmed (a timeout, 5xx, or a call that never recorded an answer) — manual, return or Auto receipt refunds alike: refund_id, idempotency_key, return_id, lines, include_shipping and error. Their units (and shipping) are held back from max_quantity until Purple Dot confirms them; retry one by sending its refund_id to Create Refund.
Query parameters:
- sales_order_id (integer, required)
- return_id (integer, optional): an RMA of the order, to prefill quantities.
Errors: 422 not_purple_dot when Purple Dot did not export the order; 422 invalid_lines when the return belongs to another order.
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.