Check return eligibility: query your order tracker for the delivery date and compare against the merchant's return window (typically 14–90 days); also check item-level non-returnable flags (e.g., perishables, digital goods, personalized items).
Authenticate to the merchant's return portal API or self-service returns endpoint using the order ID and the email address associated with the order.
Submit the return request with required fields: order ID, line item IDs to return, return reason code (from the merchant's enumerated reason list), and quantity.
Capture the return authorization number (RA number) and prepaid shipping label URL returned by the merchant; store these in the order record.
If the merchant's API does not support automated returns and only offers a web portal, emit a HITL event with the return portal URL and pre-filled context so a human can complete the return in minimal steps.
After the return shipment is received by the merchant (detectable via carrier tracking or a refund event), update the order record to 'returned' and log the refund amount when it appears.
Known gotchas
Return reason codes are merchant-specific enumerations; map from user-friendly descriptions to the merchant's exact required codes, as mismatched codes can cause returns to be rejected.
Some merchants require a photo of the defective or incorrect item before approving a return; automate photo attachment if your agent has access to the relevant image, otherwise escalate to a human.
Return shipping labels from merchant APIs may have an expiry date; generate them close to when the user will actually ship the item, not weeks in advance.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp