Returns

The return object and the allowed CRUD operations on the related resource endpoint

Returns are linked to one specific order. They get created in draft status and become requested when a customer requests to return SKUs from an order. Requested returns can be approved or cancelled. An approved return becomes shipped once it leaves the customer's address (origin). As soon as they reach the available return location (destination), shipped returns can either be marked as received and restocked to an inventory location or — in case of any errors (e.g. the customer sent back the wrong products) — be marked as rejected. Received returns can be refunded, in which case, their status becomes refunded.

Returns are still creatable and updatable even when the associated order's fulfillment status is in_progress. If needed, you can mark a return as received also directly from the requested or approved status.

Refunding from a return

As long as a return's status is received a refund process can be initiated starting from the return itself. This way a reference_refund relationship is added to the return. To do that, you need to pass two trigger attributes:

• _refund — set it as true to trigger the refund.

• _refund_amount_cents — specify a value that will be used as the amount to be refunded.

The API provides an estimated value for the amount to be refunded and exposes it in the estimated_refund_amount_cents attribute. Please consider it a gentle guess that is computed based on the price and quantity of the returned items discounted by the related discount_cent. Be aware that it might differ from the associated order's capture refund balance.

By default, the capture that will be refunded is the most recently succeeded capture associated with the related order. In the case of an order associated with multiple captures, you can also specify the exact capture (different from the most recently succeeded) to be refunded passing the reference_capture relationship when sending the triggers, provided that the specified capture is succeeded as well. Otherwise, the API will return an error that will be stored in the related resource errors. If that amount you pass is less than refund_balance_cents of the associated capture, a partial refund will be triggered (if you then want to amend the remaining balance you'll need to trigger a new refund starting from the associated order). If it's equal a full refund will be triggered. If it's greater the API will return an error.

When a refund process is initiated starting from a return, the associated order is not automatically cancelled, even if the refund is successful. If you need to cancel the order, you need to do it manually.

Data model

Check the related ER diagram and explore the flowchart that illustrates how the return resource relates to the other API entities.