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. POST /v1/returns/{return_id}/process combines this work with decisions and resolutions, so it requires all three scopes: commerce.returns.write, commerce.returns.operations.write, and commerce.returns.resolutions.write. The Receiving and inspecting guide walks one parcel through all three.
Receipts and inspections are immutable observations. Before another fact consumes an observation, correct it by creating 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. A receipt cannot be corrected after an inspection or disposition consumes it. Because automatic receipt disposition consumes matched merchandise immediately, use a policy revision with receipt_disposition_mode: manual when your workflow needs a receipt-correction window.
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,undetermined. Chooseundeterminedwhen the item's condition could not be assessed.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. Under manual receipt disposition, it becomes dispositionable. Under automatic receipt disposition, acceptance creates a successful sellable disposition and returns it in generated_dispositions. 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 /decide route only settles review_required; correct an accepted or rejected call with a superseding inspection before a disposition consumes it.
Dispositions#
A disposition targets either a receipt line or an inspection line, never both. Four of the eleven 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.