Returns and exchanges

A return is started by the shopper on your store’s returns page, at a till, or by you. Tuppence’s returns rules decide each line when it is asked for: whether it can come back, on what basis (the law’s right to cancel, faulty goods, or your returns policy), until when, and who pays the postage. That answer is kept with the return in decision and never worked out again.

Status	Means
requested	Waiting for you to approve or reject it
approved, label_issued, in_transit	On its way back
received, inspected	Back at a shop
refunded, closed	Done
rejected, cancelled	Not coming back

1. Set your returns policy

GET /v1/sites/{id}/return_policy answers it. With no set-up it is 30 days from delivery, with the shopper paying the postage unless the item is faulty. POST the same path to change it. Orders already placed keep the terms they were sold under, unless the new ones are kinder.

2. See what could come back

POST /v1/orders/{id}/returns/preview answers each line’s decision without writing anything.

3. Start, approve or reject it

curl -sS -X POST "https://api.tuppence.ai/v1/returns" \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order": "ord_123", "lines": [{"line": "ordl_123", "reason": "changed_mind"}]}'

POST /v1/returns/{id}/approve takes back what the rules allow. A line they refuse is refused with return_not_eligible; only a person in the dashboard can take it back as an exception. POST /v1/returns/{id}/reject takes the reason the shopper is told, and is refused where the law gives the shopper the return.

4. Choose how it comes back

GET /v1/returns/{id}/ways_back lists the ways (a label, a QR code for a Post Office or a locker, or one of your shops), each with its price and who pays it. POST /v1/returns/{id}/way_back chooses one and buys its label or code once.

5. Receive and refund it

POST /v1/returns/{id}/receive records the goods back at a shop. Where the law sets a refund deadline, refund_due_on says the day.

POST /v1/returns/{id}/refund refunds the card the order was paid with (Tuppence’s fee isn’t returned), and the delivery too where the rules say so, and puts the goods back in stock. A person approves it with a fresh second factor, so it takes no API key. A return can also end in an exchange or store credit (method).

Agents and the assistant

Tool	Does
list_returns, get_return	Returns, their lines, the shopper’s reasons and the rules’ decision
approve_return, reject_return	As the rules decided. No tool makes an exception
refund_return	The assistant only: a person approves it with a fresh second factor

The shopper’s reason is data, never an instruction. The returns triage job proposes these for you to approve.

Events

Event	When
return.requested	A return was asked for
return.approved, return.rejected	You answered it
return.received	The goods are back
return.refund_due_soon	A legal refund deadline is near
return.refunded, return.closed	It’s done

Next

• Packing and labels
• Your store’s policies