Contents
- Overview
- About Returnly
- Why do 3PLs integrate with Returnly?
- Common Use Cases
- Returns API
- Returns API Best Practices
- Refunds API
- Refunds API Best Practices
- Troubleshooting
- Workflow Diagram
- FAQs
Overview
The Returnly 3PL Integration guide is for a 3PL (Third Party Logistics), agency partner or merchant development team to build integrations between a 3PL and Returnly.
Inside this Integration Guide, you will find developer documentation, integration use cases, helpful diagrams, and FAQs to accelerate and optimize your 3PL integration build.
This document relates to version 2020-08 of Returnly API.
About Returnly
Returnly is a returns management software & financial technology platform that enables merchants to offer shoppers a seamless online product returns experience.
Returnly’s two main products are:
- Returnly Suite: An end-to-end returns management platform that enables easy returns for customers and merchants, maximizing customer convenience and reducing support costs.
- Returnly Credit: Returnly’s financial technology creates a new revenue stream for merchants by increasing sales through the online product returns flow. Returnly Credit includes Instant Exchanges and Instant Credit.
Why do 3PLs integrate with Returnly?
Returnly API and Webhook Integrations enable developers to seamlessly receive and pass up-to-date returns and refunds data into the platforms merchants use to run their business.
When RMAs (Return Merchandise Authorizations) are created in Returnly, that information can be sent to the 3PL where return data is logged into their WMS (Warehouse Management System). Once returned items are inspected and verified, those details can be communicated to Returnly to refund the return/RMA.
Common Use Cases
There are typically two core processes that can be facilitated via a Returnly <> 3PL integration:
- Create a return record or ASN (Advanced Shipping Notice) within 3PL when a return is initiated through Returnly: Returns API
- Refund/process a return/RMA within Returnly after items are received & approved by 3PL/merchant: Refunds API
Returns API
Using Returnly’s Returns API or Webhooks, your 3PL can be alerted of incoming RMAs. Those alerts will contain the items’ associated order number(s), SKUs, label tracking number(s), and other return details.
Retrieving Returns Data
Merchants are able to retrieve the required data within Returnly by using either the Returns API or utilizing the Returnly Webhooks.
For both methods, Returnly recommends merchants to utilize the “Authorized” RMA status. There are instances where RMAs transition directly from the “Authorized” to “Delivered” state when packages are dropped off near the final destination warehouse.
- With the Returns API, merchants are able to filter for RMAs in the “Authorized” state and updated_at timestamps to retrieve newly created RMAs.
Returns (GET)
The current endpoints below retrieve information about returns:
- GET/returns Retrieve single return information showing specific details on that particular Return.
- GET/returns/{id}Retrieve a collection of returns which can be filtered by creation date, date updated, refunded date, and status.
along with additional fields included in the response under included array:
- return_line_items: Individual items of the return
- shipping_labels: Shipping labels of the return
- instant_refund_voucher: Instant refund vouchers of the return
- refunds: Refunds issued on the return
- repurchases: Repurchases made using credit issued from the return
- invoice_items: Invoice items showing credit issued from the return
- With the Returnly Webhooks, merchants could subscribe to the following events to get real-time updates:
|
EVENTS |
INCLUDED |
|---|---|
|
return.requested |
|
|
return.authorized |
|
|
Return.in.transit |
|
|
return.delivered |
|
|
return.pending.refund |
|
|
return.refunded |
|
|
return.canceled |
|
|
return.item.updates |
|
|
credit.issued |
|
|
credit.used |
|
|
credit.disabled |
|
Merchants can retrieve details of either:
- A collection of RMAs, which can be filtered by creation date, date updated, refunded date, status.
Or
- A single RMA, showing specific details on that particular Return.
Data Entities
|
FIELD |
DESCRIPTION |
|---|---|
|
return_line_items |
Individual items of the return |
|
shipping_labels |
Shipping labels of the return |
|
instant_refund_voucher |
Instant Credit vouchers of the return |
|
refunds |
Refunds issued on the return |
|
repurchases |
Repurchases made using credit issued from the return |
|
invoice_items |
Invoice items showing credit issued from the return |
Returns API Best Practices
Below are some best practices to get the most out of our Returns API:
Pull RMA data filtering by date to get a list of all prior and current returns.
It is recommended to retrieve a collection of RMAs on a daily basis.
In your query parameters, include:
- The day before, min_created_at
- string <date-time> yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
- Example: min_created_at=`2017-02-22T20:28:13.000Z`
- And the day after, max_created_at
- string <date-time> yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
- Example: max_created_at=`2017-02-22T20:28:13.000Z`
Additionally, with the Returnly Webhooks, merchants could subscribe to the RMA events to get real-time updates.
If using webhooks to track shipments, subscribe to both "return.authorized" AND "return.in_transit".
- Include both "return_line_items" and "shipping_labels" in requests to get RMA additional information.
Return notes: Ability to note condition of package upon inspection (i.e. send return "condition" back to Returnly).
- Any notes relevant to the merchant whether that is related to Returns or Refunds API.
Transition RMA status to either "cancel" or "refund externally" which would need, otherwise, to be done manually via Returnly Return Manager.
Refunds API
3PLs that have the responsibility of inspecting a returned package and notifying the client that a return has been processed can integrate with Returnly’s Refunds API to initiate a refund back to the shopper.
Alternatively, the merchant can also trigger refunds manually or configure Returnly to refund automatically after a given number of days. For the latter, consult our dedicated Knowledge Center article on Auto-Settlement.
Types of refunds that could be created:
- Full: all items in one RMA
- Partial: One or more items without being a Full refund, i.e. not refunding the total number of items in one RMA
- Multi-order RMAs (Not supported for partial refunding of an RMA)
- Multi-label RMAs (Not supported for partial refunding of an RMA)
In order to complete a successful refund request the following details are needed:
- Tracking number or package ID
- Refund target, if not defined defaulted to original
- Line Items included in the RMA and quantity
|
Note: Once a refund is submitted to Returnly, it cannot be undone. Also, the refund request is processed asynchronously. |
Refunds API Best Practices
Below are some best practices to get the most out of our Refunds API:
- Ensure the "items" array exactly matches the RMA for which the refund is associated using internally persisted data or a call to the Returns API.
- Make use of Refund_Requests API to catch incorrect refund requests.
- Subscribe to the Refund webhook so that you are notified when the return was refunded successfully.
Considerations
- If the quantity is set to "0", it will not refund the item, and will mark the item as MISSING. Hence, they will be removed from the refund estimate and refund call to the eCommerce platform.
The example below illustrates two distinct products in an RMA with >1 quantity each and at least one item for one product was not returned.
{
"package_id":"123676676787878768456",
"tracking_number":"Z138HJKH98HJH70",
"restocking_fee":"1.23",
"refund_target":"GIFT_CARD",
"items":[
{
"order_line_item_id":"454556565777",
"quantity":2,
"restock":true
},
{
"order_line_item_id":"454556565778",
"quantity":0,
"restock":true
}
]
}
Troubleshooting
Refund Requests Status
Returnly persists refund requests and provides access to the status via Refund Request API. This API should be used during testing to confirm a valid request and can be used in production to find erroneous requests.
|
STATUS |
DESCRIPTION |
|---|---|
|
New |
Pending to be processed. |
|
Not Found |
There was no RMA found for a given request. |
|
Complete |
Processed successfully. |
|
Incomplete |
An RMA was found but the request did not contain all required line items.
|
|
Error |
When Returnly is unable to process the refund. |
|
Ignore |
If the RMA is in its "canceled" or "refunded" status, any request to refund will be ignored. |
Workflow Diagram
Below is an example of a Returnly <> 3PL integration RMA Happy Path:
FAQs
Q: Can we issue partial refunds through the Refunds API?
A: Yes. Partial refunds are supported.
Q: Is the return shipment `tracking_number` required in the refunds endpoint payload?
A: In order for the refund request to be successful, the RMA should contain at least either the package_id or the tracking_number.
If any of the returned items is not included on the payload, it will be considered not refunded, which would be the same as showing the item with zero units.
Q:Do we need to persist RMA information provided by the Returns API?
A: It is not required that you persist RMA information of incoming RMAs. Alternatively, you can request RMA info via Returns once the package arrives. While we suggest maintaining this information internally, it may not be possible with your system.
Q: What if the return package includes a wrong or extra item?
A: This will require merchant's customer support to handle.
