Returns

Returns covers everything from the customer's "I want to return this" through carrier booking, item receipt, and refund.

A return runs on the same Shipment object as a forward delivery, just with type=reverse. It's booked through the same carriers and tracked the same way. The Returns module layers a request-and-approval workflow on top: the customer raises a return, the merchant approves it, and a reverse Shipment is booked from that approved request.

You can use either layer independently. With the Returns module, Carriyo manages the full request lifecycle. Without it, you can still book reverse Shipments directly through the Shipping API. Useful when your existing system handles approvals and refunds.

The Returns module is available as a subscription add-on, covering the request workflow and the customer-facing returns portal. Reverse Shipments themselves work for any tenant.

What returns does

• Customer-initiated returns. A customer-facing returns portal (or your own UI calling Carriyo's APIs) lets shoppers raise return requests against their orders.
• Approval workflows. Each return reason carries an auto-approve flag. If every item's reason is auto-approve, the request approves on submission; otherwise it stays pending for ops to decide in the Dashboard.
• Reverse shipment booking. Once approved, Carriyo books a reverse shipment with the configured carrier and generates a return label.
• Item receipt and condition. When the return lands at the warehouse, ops records returned and received quantities and per-item condition (codes the merchant defines).
• Refund tracking. The return request carries a list of refund entries: amount, currency, reference, and dates. The merchant's finance system can record what was refunded against the return.

The two modes

Two ways to run returns through Carriyo. Pick per-merchant.

Returns API mode (full lifecycle)

Carriyo manages the return request record end-to-end: customer submits, rules approve or reject, reverse shipment is booked, items are received, refunds are recorded.

This is the right mode when you want Carriyo to be your returns system.

Reverse-shipment-only mode

You manage approvals, refund logic, and customer comms in your own system. When you decide a return is approved, you call the Shipping API to book a reverse shipment, the same endpoint as a forward shipment, with entity_type: REVERSE. Carriyo books the carrier and tracks the parcel; everything else stays with you.

This is the right mode when your existing returns workflow is elaborate and you only need Carriyo to book and track the carrier.

The model (Returns API mode)

A return request is the central object. It carries:

• A reference back to the original Order and the forward Shipments the items came from.
• A list of return items: which lines, in what quantities, and with what reason. Each item tracks approved_quantity, returned_quantity, and received_quantity independently.
• A lifecycle status: pending, approved, completed, rejected, cancelled, on_hold.
• A list of refund entries with amount, currency, and reference.

See Return request model for the full shape.

How it fits with other modules

• Orders. Returns are scoped to lines on a specific order. The order-line is the unit of return.
• Shipping. Once approved, a return produces a reverse Shipment. From the carrier's perspective it's a normal booking; the difference is direction (entity_type = REVERSE).
• Post-purchase CX. The returns portal and return-status notifications all react to the return request lifecycle.
• Carrier configuration. Capacity rules, Costing rules, Shipping rule sets, and Service Level rule sets all carry an entity_type filter. Use it to route forward and reverse traffic independently.