Return Public API: Warehouse Integration
Plans : Enterprise Platforms : All platforms
Ecommerce returns follow a reverse flow compared to the typical fulfillment process. This involves three main parties: the shopper (who initiates the return), customer service (who manages return requests and policies), and the warehouse team (who processes returned items, restocks them, or issues refunds).
Many advanced merchants automate their entire order fulfillment process, from the customer’s purchase to shipping via third-party logistics providers (3PLs) or warehouses. They expect a similar level of automation for returns, including return initiation, label generation, tracking, and inventory updates.
This integration allows AfterShip Returns to serves as an integration point, connecting the main parties—shoppers, customer service, and warehouse teams, thereby streamlining communication and automating tasks throughout the return process.
This guide is intended for merchants who wish to build a custom integration between their warehouse and AfterShip Returns. It does not depend on the eCommerce platform you use. However, as it requires the use of AfterShip Return's Public APIs, this feature is only available to Enterprise customers.
In this article, we will show you:
Return process flow post integration
User pain points
3PL / Warehouse team
Merchant / Customer service team
Syncing return data
Webhook method
API method
Marking items as received
Adding disposition of returned items
Fighting return fraud
This is what a typical return process flow looks like if you are using this integration.
Warehouse teams often don’t know in advance what will be returned, when returns will arrive, or how many packages will be coming to the warehouse.
There’s no clear indication of which merchant a returned package belongs to, leading to confusion and delays in processing.
Warehouse teams face a high volume of emails from merchants regarding the disposition of returned products, which adds to the workload.
3PLs or warehouse teams typically use their internal systems to process returns and are not familiar with or integrated into the AfterShip Returns admin porta
Merchants must send numerous emails to 3PLs or warehouse teams to provide Advanced shipping notices (ASNs), keeping them updated on incoming returns.
For merchants dealing with high-value items, refunds are often processed only after the warehouse receives the returned product.
- The quality of the returned item impacts the amount the merchant is willing to refund.
- Poor-quality returns may also affect the eligibility of the request to be refunded to the original payment method.
Merchants must engage in constant email communication with warehouse teams to confirm the quality of returned products.
There are two primary methods for extracting return details from AfterShip Returns and syncing them into the 3PL/warehouse system for processing:
Two webhook events signal that a return shipment is ready is ready to be shipped back to the warehouse.
return.shipment.provided – Triggered when a shipping label with a tracking number is generated or uploaded by the merchant.
return.shipment.recorded – Triggered when the shopper uploads the tracking number for the returned item.
Multi-location warehouse management: If a merchant has multiple return warehouse locations, it is recommended to name return routing rules by location name. This allows merchants to use the return_method.rule.name field to route returns to the appropriate warehouse location.
Alternatively, return data can be fetched by the RMA number through the API . When the return package arrives at the warehouse, the packing slip or shipping label will contain the RMA number, which can be used to fetch the return details from the returns/rma/{rma_number} API endpoint.
Ways to identify the RMA number on return packages
Enable the Generate packing slips feature, allowing shoppers to include packing slips inside the return package.
Use the custom return label reference feature to embed the RMA number into the shipping label’s reference field.
Once the warehouse confirms the receipt of the return package, the warehouse system can sync the return status to AfterShip via the /Post Receive items by RMA number API endpoint. This endpoint allows warehouse staff to mark the returned items as received and assign a grade to indicate the condition of the returned goods.
Grading options: By default, AfterShip offers grading options: A, B, C, and D. Warehouse teams should set up a mapping logic between their own grading codes and AfterShip’s standard grading options.
Once the warehouse inspects the returned items and determines their disposition, users can use the AfterShip API to associate the disposition result with the returned item.
API /Post Update return items by Return number : Warehouse users can call this endpoint to add the disposition result as an item tag to the RMA (Return Merchandise Authorization).
Admin users must pre-define the possible disposition results as item tags within the AfterShip Returns admin panel.
API users can use the API /Get item tags endpoint to obtain the tag IDs of the pre-defined item tags for the merchant’s organization.
Once warehouse integration is fully established, merchants can use AfterShip’s fraud prevention features to automate flagging suspicious returns.
Anti-fraud workflow: Admin users can set up an Anti-fraud workflow that automatically flags return requests for review if a customer repeatedly returns items that have been marked as unqualified returns by the warehouse team.
Overview
Ecommerce returns follow a reverse flow compared to the typical fulfillment process. This involves three main parties: the shopper (who initiates the return), customer service (who manages return requests and policies), and the warehouse team (who processes returned items, restocks them, or issues refunds).
Many advanced merchants automate their entire order fulfillment process, from the customer’s purchase to shipping via third-party logistics providers (3PLs) or warehouses. They expect a similar level of automation for returns, including return initiation, label generation, tracking, and inventory updates.
This integration allows AfterShip Returns to serves as an integration point, connecting the main parties—shoppers, customer service, and warehouse teams, thereby streamlining communication and automating tasks throughout the return process.
Important consideration
This guide is intended for merchants who wish to build a custom integration between their warehouse and AfterShip Returns. It does not depend on the eCommerce platform you use. However, as it requires the use of AfterShip Return's Public APIs, this feature is only available to Enterprise customers.
What you’ll learn
In this article, we will show you:
Return process flow post integration
User pain points
3PL / Warehouse team
Merchant / Customer service team
Syncing return data
Webhook method
API method
Marking items as received
Adding disposition of returned items
Fighting return fraud
Typical return process flow post integration
This is what a typical return process flow looks like if you are using this integration.
Which user pain points will this integration address
3PL / Warehouse team
Warehouse teams often don’t know in advance what will be returned, when returns will arrive, or how many packages will be coming to the warehouse.
There’s no clear indication of which merchant a returned package belongs to, leading to confusion and delays in processing.
Warehouse teams face a high volume of emails from merchants regarding the disposition of returned products, which adds to the workload.
3PLs or warehouse teams typically use their internal systems to process returns and are not familiar with or integrated into the AfterShip Returns admin porta
Merchant / Customer service team
Merchants must send numerous emails to 3PLs or warehouse teams to provide Advanced shipping notices (ASNs), keeping them updated on incoming returns.
For merchants dealing with high-value items, refunds are often processed only after the warehouse receives the returned product.
- The quality of the returned item impacts the amount the merchant is willing to refund.
- Poor-quality returns may also affect the eligibility of the request to be refunded to the original payment method.
Merchants must engage in constant email communication with warehouse teams to confirm the quality of returned products.
Syncing return data
There are two primary methods for extracting return details from AfterShip Returns and syncing them into the 3PL/warehouse system for processing:
1. Webhook method
Two webhook events signal that a return shipment is ready is ready to be shipped back to the warehouse.
return.shipment.provided – Triggered when a shipping label with a tracking number is generated or uploaded by the merchant.
return.shipment.recorded – Triggered when the shopper uploads the tracking number for the returned item.
Multi-location warehouse management: If a merchant has multiple return warehouse locations, it is recommended to name return routing rules by location name. This allows merchants to use the return_method.rule.name field to route returns to the appropriate warehouse location.
2. API method/Get return details by RMA number
Alternatively, return data can be fetched by the RMA number through the API . When the return package arrives at the warehouse, the packing slip or shipping label will contain the RMA number, which can be used to fetch the return details from the returns/rma/{rma_number} API endpoint.
Ways to identify the RMA number on return packages
Enable the Generate packing slips feature, allowing shoppers to include packing slips inside the return package.
Use the custom return label reference feature to embed the RMA number into the shipping label’s reference field.
Marking items as received
Once the warehouse confirms the receipt of the return package, the warehouse system can sync the return status to AfterShip via the /Post Receive items by RMA number API endpoint. This endpoint allows warehouse staff to mark the returned items as received and assign a grade to indicate the condition of the returned goods.
Grading options: By default, AfterShip offers grading options: A, B, C, and D. Warehouse teams should set up a mapping logic between their own grading codes and AfterShip’s standard grading options.
Adding disposition of returned items
Once the warehouse inspects the returned items and determines their disposition, users can use the AfterShip API to associate the disposition result with the returned item.
API /Post Update return items by Return number : Warehouse users can call this endpoint to add the disposition result as an item tag to the RMA (Return Merchandise Authorization).
Admin users must pre-define the possible disposition results as item tags within the AfterShip Returns admin panel.
API users can use the API /Get item tags endpoint to obtain the tag IDs of the pre-defined item tags for the merchant’s organization.
Fighting return fraud
Once warehouse integration is fully established, merchants can use AfterShip’s fraud prevention features to automate flagging suspicious returns.
Anti-fraud workflow: Admin users can set up an Anti-fraud workflow that automatically flags return requests for review if a customer repeatedly returns items that have been marked as unqualified returns by the warehouse team.
Updated on: 17/01/2025
Thank you!