Overview
What a return is and the rules that apply to all its endpoints.
A return is the product coming back from an order. It has lines (items, with orderLineId and quantity), a reason (reason), a status, the tracking of the way back (tracking) and the amount given back to the buyer (refundInCents). On some marketplaces it starts from a dispute; then disputeId links the two.
Where it fits in the journey: The order lifecycle.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/returns | List returns |
GET | /v1/returns/{returnId} | Get return |
POST | /v1/returns/{returnId}/actions | Act on a return |
All require Authorization: Bearer mk_your_api_key. See Authentication.
States
status | Meaning |
|---|---|
requested | the buyer asked for it |
approved | approved |
in_transit | the product is coming back |
received | the product arrived |
under_review | under review |
refunded | refunded |
closed | closed |
cancelled | cancelled |
refundStatus is pending, refunded or retained.
Stock
A received return with an ok review (or no review, if the marketplace has none) puts the item back in stock, once only (restockedAt). A failed review, a damaged product, does not go back. It only applies with the order stock policy on and a SKU with marketapi authority. A kit goes back by component.
Actions and webhooks
allowedActions lists action, mandatory and dueAt. Every action is a job (return.action). Events: return.created and return.updated, with no personal data. See Receiving webhooks.