Shipping & Returns Best Practice Guide
This toolkit details how you can integrate Yotpo Reviews, Yotpo Loyalty & Referrals, and Yotpo SMS & Email with your shipping or returns platform to create seamless consumer experiences that allow merchants to fully benefit from both solutions.
Here are the main use cases covered in this guide:
- Update the time of Yotpo Post Purchase Review Request Email.
- Display star ratings on purchased products and recommended products on an order tracking page or widget.
- Trigger messages based on shipment status updates and other custom events.
- Capture SMS and email subscribers as part of order-tracking pages or widgets.
- Reward a customer with loyalty points when a shipment was delayed or incentivize them to choose a different shipment or return option.
Have you registered your app yet?
Before you start building your app on top of Yotpo’s App Market API, you first need to register it with us. If you haven’t done so yet, refer to the steps in our Welcome guide.
Yotpo Reviews
Update the time of Yotpo post-purchase review request email
Yotpo receives orders from eCommerce platforms based on different order statuses and enters these orders into a queue for post-purchase emails to be triggered a set number of days later, according to the setting defined in your Yotpo account. Merchants that are on Shopify can also leverage delivery statuses that are already available in Shopify.
Yotpo’s system checks each order that has not yet triggered a review request on a nightly basis (at midnight GMT), to see if the order status or fulfillment date has changed. Please note, we require all items in the order to be fulfilled before we receive it from Shopify.
Merchants typically want to trigger review requests only once they know an order has been delivered. If you are updating the shipping status in Shopify directly to “delivered”, then this information will be passed to Yotpo by default and the merchant can trigger their review request emails based on that status.
If you are not updating the status in Shopify (or the eCommerce platform) directly, you can update the shipping status directly in Yotpo. To do so, you’ll need to make the following API calls to update the timing of a review request:
- First, retrieve the order to get the Yotpo ID ('yotpo_id' nested under “orders”).
- Once you have the 'yotpo_id' from the previous call, you can retrieve the order fulfillment to get the order details and Yotpo Fulfillment ID (“yotpo_id” nested under “fulfillment”)
- Now, update the order fulfillment using the Yotpo Order ID and Yotpo Fulfillment ID. The call is a “Patch” so you can update just the relevant information, in this case, the "shipment_status" will need to be set to “delivered” to start the count in Yotpo for the review request sent.
Once the order was set to 'delivered', the review request will be added to the cue and this status can not be changed/postponed.
Display star ratings on purchased products and recommended products on an order tracking page or widget
To easily implement this use case, follow the relevant section of the “Product Recommendations” best practice guide.
Yotpo SMS & Email
Trigger messages based on shipment status updates and other custom events
Through our Create or Update custom customer event endpoint, you can send us any event that the merchant can trigger SMS flows based on.
Some examples of communications that can be sent include updates on order status, updates on shipping status when a customer returns an item or initiates an exchange, and much more!
Within this call, you can also include any metadata associated with the event for creating personalized segments and campaigns. Additionally, you can include any relevant elements in the “event_properties” such as custom URLs, delivery dates, etc, to be used as shortcodes within the SMS. We highly recommend sending us both the tracking ID and the URL for the custom tracking page so the merchant can include this in their SMS body.
Once the custom event has been sent, you can follow the below steps to set up an SMS campaign:
Once you send the event, you can access it in the “Custom Triggers” section of the SMS & Email admin (located under Flows & Automations)
In order to use them in a flow, you’ll need to manually enable the toggle to “display as a trigger”
You can view and edit any flows in the “flows” section, located in the same “flows & automations” tab as the Custom Triggers.
Important!
We require you to send all sample payloads in a Google doc to [email protected]. Once the integration is tested and approved, we will reveal the triggers to all merchants in the flows section of the admin (as opposed to in the custom triggers section).
Please also provide us with a start install URL for the integration and a link to the integration help article so we can direct merchants who have not yet installed the integration to be able to do so.
This guide contains more detailed information on how to leverage SMS & Email flows.
Please note:
We do not currently support building conditional logic leveraging properties sent inevent_properties, but this is on our roadmap for future development.
Capture SMS subscribers as part of order tracking pages or widgets
There are 2 ways you can achieve this:
-
Using the Yotpo out-of-the-box embedded code as explained here
- Each form has its own unique code, so you will need the merchant to pass you their code so you can properly display the form.
-
Add an SMS capture option that automatically adds a checkbox and legal language in the shipment tracking page if the customer is not already subscribed:
- This will require you to ask the merchant for the SMS & Email list ID they would like to have the subscribers added to (this will be used in the Create subscriber endpoint).
- Check if the customer is already subscribed on the page (using the eCommerce platform customer ID) using the Retrieve customers endpoint.
- If the customer is not subscribed already, display the checkbox with the standard consent language in the screenshot here (the rest of the terms will be added by the merchant). Learn more in the Recommended Terms of Service and Privacy Policy when using Yotpo SMS and Email.
When the customer provides a valid phone number, send their details first (name, etc.), wait 60 seconds, and then send the opt-in status: - Yotpo will send them a welcome message based on the standard Yotpo welcome flow (in the future, will allow customizing per opt-in source) and add them to the list of the merchant’s choice.
Yotpo Loyalty & Referrals
Reward a customer with loyalty points when a shipment was delayed or incentivize them to choose a different shipment or cancellation option
Allow merchants to configure a campaign that will automatically reward the customer with loyalty points (and trigger messages/info into the Help desk cases you open) to notify the customers of the automatic reward.
This can be done using Yotpo’s custom action API (the merchant needs to configure the custom action in Yotpo as described here).
Updated 12 months ago