2026-07 Prevent mixing of referenced and unreferenced returns
To improve the auditability of return sales, the 2026-07 Update Sale endpoint (PUT /api/2026-07/sales/{sale_id}) now validates product references when completing a parked return (state transitioning from parked to closed).
Return types
| Return type | Condition | Result |
|---|---|---|
| Unreferenced | No return_for (not linked to an original sale) | Allowed |
| Referenced | return_for set and every returned product is part of the linked sale's return history | Allowed |
| Mixed (blocked) | return_for set but one or more returned products are not part of the linked sale's return history | Rejected with HTTP 422 |
Eligible return history
When return_for links a return to an original sale, each returned product must appear in that sale's return history. Eligible products include:
- Products sold on the original sale
- Products acquired through an exchange on a prior closed return against the same original sale
A returned product does not need to have been on the original sale itself. If a customer previously exchanged an item on an earlier return against that sale, returning the exchanged product is valid. Products with no history against the linked sale are treated as unreferenced and will cause the request to fail.
What changed
- This validation applies on the 2026-07 API only when using the date-based Update Sale endpoint—not on earlier API versions such as 2026-04 or 2026-01.
- The check runs when closing a return sale, not when creating the parked return.
- Integrators should ensure each returned line item corresponds to a product in the linked sale's return history before finalising.
For the overall return workflow, see Sale returns.
🔒 Requires: sales:write scope