Auth: X-Agent-Key: sq_agt_*. Scopes: read_returns, write_returns. Status flow: requested → open (approved) → closed; or declined / canceled.

​
Endpoints

  • POST /returns — request { "return": { "order_id":"ord_…","return_line_items":[{"order_item_id":"…","quantity":1,"return_reason":"defective","restock_type":"return"}] } }
  • GET /returns?order_id=&status= (cursor) · GET /returns/{id}
  • POST /returns/{id}/approve · /decline · /close · /cancel
  • POST /returns/{id}/reverse_deliveries — attach return tracking { "tracking_company":"UPS","tracking_number":"1Z…" }
Return reasons: unwanted, defective, wrong_item, size_too_small, size_too_large, other. Restock types: no_restock, cancel, return. Emits returns/request|approve|decline|close.
Closing a return records refund intent in the event payload; issuing the actual refund runs through the payment ledger (transactions/refunds) and is wired separately.