Returns and return-to-vendor

Reverse logistics is two connected flows: goods coming back from customers, and goods going back to suppliers. The hinge between them is disposition — deciding whether a returned item is restockable, scrap, or the supplier’s problem.

Customer return

curl -X POST https://api.stateset.com/api/v1/returns \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "order_id": "ord_9x2", "items": [{ "sku": "SHOE-RED-10", "quantity": 1, "reason": "defective" }] }'

curl -X PATCH https://api.stateset.com/api/v1/returns/{id}/approve \
  -H "Authorization: Bearer $STATESET_API_KEY"

Approval authorizes the return — the RMA — before goods move. What arrives then goes through receiving like any inbound goods, with condition recorded honestly, because condition drives everything below.

Approval is a policy decision, and policy is where agents get argued into things. If an agent handles returns, put the approve call behind the decision gate: the gate rules on return_allowed(order_941) from your actual policy, with cited proof — and “the customer was upset” is not a rule it knows.

Refund

curl -X POST https://api.stateset.com/api/v1/payments/{payment_id}/refund \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Idempotency-Key: rfnd_ret_456" \
  -H 'content-type: application/json' \
  -d '{ "amount": "128.00" }'

Refund against the original payment, and decide your trigger deliberately: refund-on-approval is customer-friendly and eats fraud; refund-on-receipt holds cash until goods arrive. Either is fine — mixing them per-agent-mood is not. The refund posts to the ledger and shows in order to cash views automatically.

Disposition

The returned unit is now inventory of uncertain quality. Route it:

Condition	Action
Resellable	Put away to a sellable location
Uncertain	`POST /api/v1/quality/holds` — off sellable stock while inspected
Defective, supplier’s fault	Return to vendor, below
Defective, scrap	`POST /api/v1/serials/{id}/scrap` for serialized goods; inventory adjust with reason otherwise

For a suspected pattern — the third cracked sole this week — open an NCR (POST /api/v1/quality/ncrs) and disposition the lot as a whole, not unit by unit: quality holds and NCRs connect a defect to every unit that shares its lot.

Return to vendor

curl -X POST https://api.stateset.com/api/v1/vendor-returns \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "supplier_id": "sup_88", "items": [{ "sku": "SHOE-RED-10", "quantity": 12, "reason": "defective_sole" }] }'

curl -X POST https://api.stateset.com/api/v1/vendor-returns/{id}/submit  -H "Authorization: Bearer $STATESET_API_KEY"
curl -X POST https://api.stateset.com/api/v1/vendor-returns/{id}/process -H "Authorization: Bearer $STATESET_API_KEY"

submit sends it to the supplier for authorization; process executes the physical return and relieves inventory. The money comes back as a vendor credit (POST /api/v1/vendor-credits, applied against future bills) — suppliers rarely wire cash, so model what actually happens.

Close the loop or the RTV quietly becomes a write-off: goods shipped back, credit never issued, and nobody notices because inventory already looks right. Track open vendor returns against received credits (GET /api/v1/vendor-returns?status=processed vs GET /api/v1/vendor-credits) — the gap between them is money owed to you.

Order to cash — the forward flow being reversed
Traceability — lots, serials, and quarantine
Object: the return — every field, and which are nullable

Overview

Quickstarts

Commerce Workflows

Order Management

Returns & Warranties

Supply Chain

Agent Development

Knowledge & RAG

Response Features

Advanced Features

Integrations

Commerce Network

Self-Hosted

Best Practices

E-commerce Workflows

Returns and return-to-vendor

Returns and return-to-vendor

Customer return

Refund

Disposition

Return to vendor

​Returns and return-to-vendor

​Customer return

​Refund

​Disposition

​Return to vendor

​Related

Returns and return-to-vendor

Customer return

Refund

Disposition

Return to vendor

Related