Return resolutions represent buyer-value outcomes. Previewing is side-effect free. Creating an ordinary proposed resolution reserves Return value capacity, and confirming it freezes the calculation and starts or gates downstream effects. The Return resolutions guide covers the flow end to end.
Effects remain normal Flint resources. Refund resolutions link Refunds, exchanges and replacements link Orders, and buyer balances link PaymentIntents. Read execution_blockers and linked effect statuses instead of treating a successful API response as proof that money moved or merchandise shipped.
Types#
| Type | Outcome |
|---|---|
refund | Money back on the original payment |
exchange | Different merchandise, with any difference settled either way |
replacement | The same merchandise again, with no money moving |
no_monetary_action | Goods come back and no value is owed |
correction | Adjusts a resolution that already settled |
Store credit is reserved and not published until Flint has a reconciled credit ledger. A refund goes to the original payer and payment method, including on a gift return; where that is unacceptable, decline the monetary resolution.
Lifecycle#
proposed to pending to partially_fulfilled to fulfilled, with requires_action, failed, and canceled as the ways out. requires_action means something outside Flint has to happen, usually the buyer paying an exchange balance.
A confirmed resolution stays pending while execution_blockers names what it is waiting for.
| Blocker | Cleared by |
|---|---|
handoff_pending | The buyer handing merchandise to a carrier |
receipt_pending | The warehouse recording arrival |
inspection_pending | An inspection and its acceptance decision |
manual_release_pending | A call to /release |
buyer_payment_pending | The buyer paying a balance |
refund_pending | The refund settling |
replacement_order_pending | The replacement Order being created |
fulfillment_pending | The replacement shipping |
credit_effect_pending | A linked credit effect completing |
The first three follow from refund_timing on the decision (after_handoff, after_receipt, after_inspection), which is how you avoid paying out for goods that never arrive.
Adjustments#
Fees and credits are adjustments on the resolution rather than separate objects, so they stay in the same arithmetic as the refund: restocking_fee, return_shipping_fee, other_fee, goodwill_credit, price_correction, other. Each carries a value_effect of deduction or credit and rolls up into the Return's financial_summary as deduction_money or credit_money, never netted invisibly into refunded_money.
Corrections#
A correction is a new resolution with resolution_type=correction and corrects_return_resolution_id. Its target must be fulfilled and belong to the same reopened Return. Corrections contain applied credit or deduction adjustments but no Return line allocations, replacement lines, or pricing basis. They preserve the original resource graph and create a normal compensating Refund for positive net buyer credit when confirmed. Deductions may offset a credit to zero, but a correction that leaves the buyer owing money is rejected: a buyer pays through a checkout, and a correction has no order to check out. Reverse lookup uses the corrects_return_resolution_id list filter.
Writes#
PATCH /v1/return-resolutions/{return_resolution_id} owns both line_items and replacement_line_items. When either array is present, it replaces that collection atomically and requires the parent resolution's expected_version. Retain a child by sending its stable child ID, omit it to remove it, or omit the child ID to add a member. A replacement line takes exactly one of variant_id, bundle_id, or name. The /release action is available only while action_reason is manual_release.