Return reasons are stable, merchant-visible explanations for why a buyer requested a Return. Flint provides a default reason set, and merchants can add or archive their own reasons. Return lines freeze the selected reason identity and display name so archived reasons remain understandable in historical records.
Built-in reasons#
These reasons are available in every merchant environment without setup. Send the ID in line_items[].return_reason_id; the handle alone is not accepted. Built-in reasons cannot be edited or archived. A reason that requires a note also requires buyer_note on the return line.
| Handle | Return reason ID | Note required |
|---|---|---|
changed_mind | rrsn_1T6HXAX0CEXP6YA5K1T392KJE6 | No |
too_small | rrsn_7264NP74WFWQFJM9ZK37KGBW31 | No |
too_large | rrsn_51T64508KCQ9TX9BXY67TPM3ZQ | No |
damaged_on_arrival | rrsn_5PACJDCF4YPWRCH9JNP5Y6THDQ | Yes |
defective | rrsn_3BQ939HAEA2C8N5QWG4ZSDA7HV | Yes |
wrong_item | rrsn_33250Y53P4V7EV7XZ3GYHRQHCA | Yes |
arrived_late | rrsn_0EMCCQEJKQJJCNP72CJ98MMXG5 | No |
no_longer_needed | rrsn_51572JN88BP55HN0V6EYDQ1K3H | No |
other | rrsn_0G0YF6HGRX0HCWX4939BQNMC8M | Yes |
Reason vocabularies#
Buyer reasons are distinct from inspection findings, decline reasons, override reasons, and Refund reasons. Keep those facts separate even when their human wording is similar: a buyer saying "damaged" and a warehouse finding damaged are different claims about the same parcel, and the difference is the point when one of them is wrong.
| Vocabulary | Supplied by | Field |
|---|---|---|
| Return reason | The buyer | return_reason_id on the Return line |
| Inspection finding | The warehouse | finding_codes on an inspection line |
| Decline reason | The merchant | decline_reason on a decision |
| Override reason | The merchant | override_reason, required when deviating from an active policy |
| Refund reason | Flint | reason on the Refund, mapped from the buyer's return reason |
A Refund raised by a Return resolution derives its own reason from the buyer's: defective becomes defective_product, wrong_item becomes wrong_item_shipped, too_small, too_large, and damaged_on_arrival become not_as_described, arrived_late becomes arrived_too_late, changed_mind becomes customer_changed_mind, and no_longer_needed becomes requested_by_customer. Reasons you define yourself have no equivalent and map to other, as does a Refund covering lines that gave different reasons.
Writes#
handle is the stable identifier you match on; name is what a buyer reads. is_note_required forces a free-text note when the reason is chosen, which is worth setting on anything you would otherwise have to email the buyer about.
When updating a merchant reason, omit category_handles to keep the current list and send category_handles: [] to clear it. Send description: null to clear the description.
Archiving stops buyers selecting a reason. Returns that already recorded it keep the frozen name, so tidying the list never changes what an old Return means.