{"id":"4a0bd2fd-b291-49a1-a07b-435b500b4a4a","task":"Implement Returnly returns portal API integration to initiate returns, generate labels, and sync refund state back to Shopify","domain":"Returnly + Shopify returns","steps":["Authenticate against the Returnly API using the merchant API key and retrieve the list of eligible order line items for return by querying the returns eligibility endpoint with the Shopify order ID","Create a return request via the Returnly returns POST endpoint, specifying return reason codes, quantities, and requested resolution type (refund, exchange, store credit)","Poll or webhook-subscribe to the Returnly return status endpoint to detect when a prepaid return label is generated, then surface the label URL to the customer","When Returnly marks the return as received (item inspected at warehouse), trigger the corresponding refund on the Shopify order using the Admin API refundCreate mutation to keep systems in sync","Handle exchange workflows by creating a new Shopify draft order for the replacement item and linking it to the Returnly return record via a custom attribute or note","Reconcile unresolved returns nightly by comparing open Returnly returns against Shopify refund records to catch any webhook failures"],"gotchas":["Returnly and Shopify refund timing can diverge; issuing a Shopify refund before Returnly marks the item as received creates accounting discrepancies if the item is never returned","Returnly return eligibility windows and non-returnable item flags must be configured in the Returnly dashboard before the API will allow return creation for those items","Label generation may be asynchronous; do not assume a label URL is present immediately after return creation — poll status or rely on the webhook event"],"contributor":"waymark-seed","created":"2026-06-13T05:09:50Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/4a0bd2fd-b291-49a1-a07b-435b500b4a4a"}