Docs
Sign in

Reverse shipments

Updated May 26, 20263 min read

A reverse shipment is a Shipment with entity_type=REVERSE. It moves a parcel from the customer back to the merchant. Common use cases include product returns, warranty swaps, recalls, and B2B returns of unsold stock.

The same Shipment object models forward and reverse. From the carrier's perspective they're symmetrical: pickup at one address, dropoff at another. The difference is purely directional: forward means merchant → customer; reverse means customer → merchant.

When this is the right tool

Reverse shipments via the Shipping API are the right choice when:

  • You're managing the return lifecycle yourself. Approval, refund logic, and customer communications are all handled in your system. You only want Carriyo to book and track the carrier.
  • You don't need a return request record. No item-condition tracking, no quantity counters, no Carriyo-managed lifecycle. Just "book a return parcel".
  • You're returning unsold stock. A B2B flow where products ship back from a retailer to the supplier. No return request needed, just shipping logistics.

If you want Carriyo to manage the return request lifecycle (approval, item conditions, refunds), use the Return request model instead.

How it differs from forward shipments

Almost nothing differs in the shipment fields:

  • The pickup address is the customer's address (where the parcel is collected from).
  • The dropoff address is the merchant's warehouse.
  • The entity_type field is set to REVERSE.
  • Items describe what's being returned (often imported from the original forward shipment).

Some carrier-specific differences are common in practice:

  • Some carriers offer return-specific service codes. See the carrier's connector page for the field reference.
  • Pickup scheduling for returns is often simpler than forward scheduling. The customer leaves the parcel at the door or drops it at a location.

Routing rules for reverse traffic

Reverse traffic is routed via the same rule engines as forward traffic, with a direction filter:

  • Shipping rule sets and service level rule sets carry an entity_type field (FORWARD or REVERSE). Most merchants run separate rule sets per direction. The cheapest forward carrier isn't always the cheapest return carrier.
  • Capacity rules and Costing rules also carry an entity_type filter, so reverse traffic doesn't compete with forward capacity and can be costed independently.

Carrier accounts themselves are direction-agnostic: the same account can handle forward and reverse traffic. Direction-based routing is done via the rule sets, not at the account level.

How it relates to a return request

When Carriyo's full return request workflow is used, the request produces one or more reverse Shipments on approval. The linkage:

  • Each return item carries a list of reverse_shipments: the IDs of the Shipments carrying that item back.
  • The Shipment carries a return_request_id reference back to the parent return request.

When a reverse Shipment reports DELIVERED, Carriyo increments the returned_quantity on the matching return items and fires a returned_update webhook. The return request status does not auto-transition. Moving the request to completed or recording receipt requires a Dashboard action or a call to the /receive or /complete API endpoints.

How it fits with other modules