A return is a new logistics journey, not a rewind of the outbound timeline. The original delivery remains true even after a customer sends the item back. Store a separate return shipment cycle and connect it to the order in your own application.
Carrier tracking can show movement and reported delivery to the return destination. It cannot establish that your warehouse inspected the item or that your payment processor issued a refund. Those milestones need their own authoritative systems.
Keep outbound and return records separate
Use a new shipment record and idempotency key for the return parcel. Keep your return authorization ID in your application and map it to the record. If you reuse an order reference, distinguish outbound and return roles in your own data model so a listing does not mix them silently.
Trace’s tracking identity is immutable for a shipment cycle. Replacing the original number would destroy the meaning of its evidence. Preserve the original record and create a distinct cycle even when the carrier later reuses a number.
Use evidence from the system that owns each milestone
Render carrier milestones and merchant milestones with different labels. A parcel reported delivered is a candidate for warehouse reconciliation, not automatic proof of an accepted return.
| Milestone | Source of truth | Customer wording |
|---|---|---|
| Return authorized | Merchant returns workflow | Return approved; follow the return instructions. |
| Parcel moving | Verified carrier observation | Return parcel in transit. |
| Carrier reports delivered | Carrier observation | Carrier reports delivery to the return destination. |
| Warehouse received / inspected | Warehouse or returns system | Return received / inspection complete. |
| Refund issued | Payment system | Refund issued, with the actual transaction date. |
Reconcile shipment updates before triggering business actions
Verify and deduplicate webhook events before updating the return view. Use the shipment revision to prevent an older delivery from replacing newer evidence. Keep warehouse acceptance and refund state out of that handler unless your separate business process explicitly validates those transitions.
An exception on the return journey should create a support task with the carrier evidence. It should not automatically cancel a refund promise or create a new payment. Make any decision that affects the buyer’s money a deliberate merchant workflow.
Rehearse missing scans and conflicting updates
Test a return with no first scan, one delivered to the wrong facility according to a later source update, and one delivered while warehouse intake is still pending. Ensure a later outbound event cannot overwrite the return status. Use labeled fixture data in the timeline builder and verify the real integration with authorized parcels.
Common questions
Does Trace generate return labels or issue refunds?
No. Use your shipping and payment systems for those actions. Trace supplies tracking evidence and UI building blocks for the parcel journey.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.