Return operations record physical facts. Receipts state what reached a Flint Location, inspections state what an operator observed, and dispositions authorize the final merchandise outcome. Corrections create superseding observations instead of editing history.
These routes use the commerce.returns.operations.write scope and do not grant refund or resolution authority. That separation lets a warehouse or WMS integration record custody and condition without permission to move buyer funds. The Receiving and inspecting guide walks one parcel through all three.
Receipts and inspections are immutable observations. To correct one, create a replacement carrying supersedes_return_receipt_id (or the inspection equivalent) and a correction_reason. The original stays readable with an observation status of superseded.
Receipt line shapes#
A receipt line takes one of three shapes, and the shape decides what its quantity is allowed to do next.
| Shape | Send | Effect |
|---|---|---|
| Matched | return_line_item_id | Counts toward received_quantity and releases after_receipt refund timing |
| Unverified | unverified_item with a name and SKU | Counts toward no line and releases no gate. Raises a merchandise_exception blocker until verified |
| Excess | quantity beyond what was approved | Counts as excess |
Verify an unidentified line with POST /v1/return-receipts/{return_receipt_id}/line-items/{return_receipt_line_item_id}/verify once an operator establishes the identity. Unverified and excess quantity can only take a non-inventory outcome such as discard, donate, or return_to_buyer, because Flint does not know which inventory item to increase.
Inspections#
An inspection names the return_receipt_id it is checking and the location_id it happened at. Each line answers three separate questions, and all three are required:
conditiongrades the item:new,unopened,opened,used,damaged,defective,incomplete,unknown.finding_codesrecords what was discovered:matches_expected_item,wrong_item,damaged,defective,used,missing_parts,empty_package,counterfeit_suspected,other.acceptance_statusis the call:accepted,rejected, orreview_required.
Several words appear in both condition and finding_codes and mean different things there, so read the field name alongside the value.
Accepted quantity satisfies after_inspection refund timing and becomes dispositionable. review_required defers the call instead: it raises an inspection_review_required blocker that holds the Return open until POST /v1/return-inspections/{return_inspection_id}/line-items/{return_inspection_line_item_id}/decide settles it with an acceptance_status and an acceptance_decision_reason of inspection_result, return_policy, manual_review, or other. The same route corrects an acceptance call that turned out to be wrong.
Dispositions#
A disposition targets either a receipt line or an inspection line, never both. Four of the twelve types change stock levels at the inventory_location_id you name.
| Disposition type | Stock effect | inventory_location_id |
|---|---|---|
sellable | Adds to sellable stock | Required |
quality_control | On hand, not sellable | Required |
damaged | On hand, not sellable | Required |
quarantined | On hand, not sellable | Required |
lost | None. Records that the unit never arrived | Required |
repair, refurbish, liquidate, donate, discard, return_to_buyer | None | Rejected |
lost takes a location but moves no stock; it records where the loss was booked. The last row rejects inventory_location_id rather than ignoring it, so sending one fails the request.
A failed disposition exposes retry, which preserves the disposition and effect identities so stock cannot move twice. When the type, destination, quantity, or source has changed, create a new disposition naming replaces_return_disposition_id instead. Replacement transfers only unused capacity, and both retry and replacement are refused once an inventory effect starts processing.