​
Let customers start returns on your store

Customers can ask for their money back or swap an item for another size or colour themselves, without emailing you. Turn it on: open Returns (platformdtc.com/returns), choose Turn on, add the address customers send returns to, and save. The address is required. What the customer sees: a returns form on your store (at /pages/returns). They find their order with its order number and the email or ZIP code on it, pick the items, say why, and choose money back or an exchange. They can add a note and up to 3 photos. Only items still inside your return window can be picked. Approve requests: choose how requests are handled.
  • I review each one. Requests wait on the Returns page, tagged From customer, with what the customer asked for, their note and photos. Nothing happens until you approve.
  • Approve automatically when inside my return rules. Requests inside your return window are approved at once. Anything outside your rules still waits for you.
Exchanges: approving an exchange (Approve & send new item) creates a free order for the new size or colour, which ships like any other order. Exchanges are for the same product at the same price. Money back: when the items arrive, choose Mark received & refund. The price of the returned items goes back to the customer’s original payment, minus your restocking fee if you set one. Choose Mark received without refund if you are settling it another way. Your return window, who pays return shipping and the restocking fee come from your Return rules in Settings → Policies (Store policies). You choose whether customers can ask for money back, an exchange, or both.

​
For developers

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…" }
  • GET /returns/self-serve — { settings: { enabled, approval: "review"|"auto", refund, exchange, return_address }, return_rules, page_path }
  • PUT /returns/self-serve — any subset of settings. Turning enabled on needs a return_address, and at least one of refund / exchange.
Returns carry source (merchant | customer), resolution (refund | exchange | null), customer_note, photos[], settlement ({ kind, message, refunded_cents, replacement_order_id, replacement_order_number, at }) and, per line, title, exchange_variant_id and exchange_variant_title. 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.
For a customer return asking for money back, POST /returns/{id}/close refunds the items (minus the restocking fee in the return rules) to the original payment; send { "refund": false } to close without refunding. For a customer exchange, approve creates the replacement order. For returns you create yourself, closing records refund intent in the event payload; issuing the refund runs through the payment ledger (transactions/refunds).