Returns

Scope

This door applies ONLY to a return shipped directly back to you (model A) — you never see or act on a return routed through a Linra sorting point. A request whose destination isn’t your own vendor id (or that has no destination bound to you at all) is reported as 404 NOT_FOUND_RETURN_REQUEST — indistinguishable from a nonexistent id. Every action here requires the Orders capability.

The lifecycle

1. PATCH /api/v1/scent/returns/{id}/received — confirm you received the returned item. Only valid from InTransit.
2. PATCH /api/v1/scent/returns/{id}/inspection/start — start your own inspection. Only valid from Received.
3. POST /api/v1/scent/returns/{id}/evidence — upload one or more damage photos/documents (a plain https:// URL — there is no file-upload endpoint). At least one Photo is required before your proposal is accepted.
4. PATCH /api/v1/scent/returns/{id}/inspection/propose — record your own proposed outcome (AcceptedDefect, AcceptedSound, or Rejected).

Your proposal is never authoritative

Linra’s own assessment is always decisive — proposing an outcome never transitions the request’s status and never triggers execution (a refund, if one is due, only happens once Linra records the real decision). If you propose Rejected, the request is flagged for staff review — you have no further action to take after that.

If no evidence has been uploaded yet, inspection/propose is rejected with 422 BUSINESS_RETURN_INSPECTION_EVIDENCE_REQUIRED.

What you get back

Every action returns the current state of the return request, deliberately excluding the reselling partner’s identity, every internal-staff identity, and every cost-attribution fact (who bears the cost, whether the original shipping fee is refunded, any recoverable-cost figure) — none of it is your business. The inspection summary likewise carries no receivingParty field — every row reachable through this door is, by construction, always destined to you, so there is nothing to disambiguate. You see: the request id, your RMA reference (returnRequestNumber), its lifecycle timestamps, the inspection summary (received/started timestamps, window deadline, Linra’s decided outcome once one exists, your own proposed outcome, whether it’s flagged for staff review, and your uploaded evidence), and the returned line(s) — variantId/sku (so you can identify the physically-returned item), quantity, and reason code — no money field of any kind.

Silence has consequences

If a window elapses with no decision from either you or Linra staff, the request is automatically accepted as a defect — a decision that still moves real money (the refund/commission-reversal chain fires the same way an explicit Linra decision would). There is no upside to letting a request sit undecided: confirm receipt, start your inspection, and upload evidence promptly.