Context: This guide is for merchants who do not use an external WMS or ERP. By using this setup, you turn your Shopify Admin into your warehouse reconciliation tool. When your team physically restocks an item in Shopify, the Shopify Return API acts as the bridge to notify yayloh, ensuring your inventory and customer refunds stay perfectly in sync without manual data entry.
High-level Requirements
[yayloh → Shopify] Create Expected Return When a customer starts a return, yayloh creates a "Return" record in Shopify. This alerts your team that a package is on its way.
[Shopify → yayloh] Restock Notification When your team marks an item as "Restocked" in Shopify, Shopify notifies yayloh that the inspection is complete and the item is "OK."
[yayloh] Automation yayloh receives the restock trigger and automatically issues the refund or gift card based on your workflow rules.
How the Solution Works
Step 1: Initiating the Return (yayloh)
When a customer requests a return via your yayloh portal, yayloh uses the returnCreate mutation.
What happens in Shopify: A "Return in progress" status appears on the Shopify Order.
The "Expected" Record: This creates a Reverse Fulfillment Order. This is the document your warehouse staff will use to "check in" the items.
Step 2: Tracking & Identification
yayloh generates the return shipping label and attaches the details to the Shopify return.
Identification: The warehouse team can identify the parcel using the Shopify Order Number (e.g., #1234) clearly printed on the yayloh return label or packing slip.
Step 3: Physical Receiving (In the Shopify Admin)
When the parcel arrives at your warehouse, your staff performs the following steps directly in Shopify:
Open the Order in the Shopify Admin.
Click on the '...' next to the "Return in progress" banner.
Select items and Click "Restock" for the items that have arrived and passed inspection.
Step 4: Closing the Loop (Shopify → yayloh)
The moment your staff clicks "Restock" in Shopify, Shopify sends a webhook (reverse_fulfillment_orders/dispose) to yayloh.
The Result: yayloh updates the return status to "Inspected OK" and triggers the automated refund or exchange immediately.
Benefits of this Approach
No WMS Required: This is the ideal method for merchants who manage inventory solely within Shopify and do have a warehouse management system (WMS). You get WMS-level automation without the extra software costs.
Live Inventory: Your "Available" stock levels in Shopify are updated the moment the item is restocked. Also easier handling of multiple location restocks.
Centralized Data: Your warehouse staff stays in the Shopify Admin they already use for fulfillment.
Limitations & Edge Cases
Damaged or Missing Items: The Shopify Admin "Restock" flow is designed for items returning to inventory. If an item is damaged, missing, or fails inspection:
Action Required: Do not restock the item in Shopify.
Resolution: These cases must be handled manually within the yayloh dashboard or Shopify Order page to ensure the customer is not automatically refunded for a damaged product.
Handling Exchanges & Sales Reporting
If you use yayloh to manage Exchanges, there is an additional step to consider within the Shopify Admin:
For refunds or store credits, Shopify usually closes the "Return in progress" status once the financial transaction is complete.
For exchanges where a new order is created and no refund is issued against the original order, Shopify may keep the return status as "Expected Refund."
Action Required: Once the item is restocked, your team should optionally mark the return as closed in the Shopify Admin to keep your order list clean.
Technical Resources
App Setup: Ensure your yayloh integration is configured to subscribe to
reverse_fulfillment_orders/disposewebhooks.Shopify Guide: Managed Returns in Shopify