- v1.0.0-latest-prod
The Return Authorization lifecycle consists of four possible steps:
Estimate Return
Allows the user to see what a return would look like, but doesn’t actually create a new return.
Create Return
Creates a new Return Authorization as a customer or as an admin.
Confirm Return
Registers all or part of a particular Return Authorization as returned and received by the seller.
Cancel Return
Cancels any of the return that hasn’t already been confirmed.
|
Note
|
All interactions with returns are always within the scope of a single Order. A Return Authorization can cover items from multiple fulfillments within that Order. |
See the Return API spec for request and response details.
The endpoint to estimate a return would normally be used to show a customer or admin what their estimated totals will be for their return once it is submitted.
The process to estimate the return is the same as for creating a return, except that the Return Authorization will not be persisted, and no messages will be sent.
A return is initiated through the creation of a ReturnAuthorization via OrderOperations and the OrderService, using a request which specifies any quantity of Order Fulfillment Items within an Order.
These items can be across multiple different fulfillments on the Order, as long as those fulfillments are already FULFILLED (see Statuses and Transitions).
ReturnOperationEndpoint receives a ReturnRequest to create a return
ReturnOperationService orchestrates the creation of the return
OrderProvider reads the requested Order from OrderService
FulfillmentProvider reads all Order Fulfillments for the Order from OrderService
ReturnProvider reads all Return Authorizations for the Order from OrderService
ReturnRequestValidator verifies that the return is valid
Order Fulfillments contain sufficient quantity for the requested return items
Order Fulfillments containing items are already fulfilled
Items aren’t already being returned in other Return Authorizations
ReturnGenerationService generates the new Return Authorization
Initial status should be PENDING
Estimate shipping charge and assign tracking number
Calculate estimated refundable amounts for return items
If returning only part of a fulfillment, use the FulfillmentSplittingService to determine the correct split monetary amounts for those items (see Fulfillment Splitting)
ReturnProvider persists the new Return Authorization in the OrderService
A Return Created message is published, containing the request, new Return Authorization, order, and all the order’s fulfillments
Return the new Return Authorization
Once returned items are received by the seller, they should be marked as "confirmed" through the confirmation endpoint, using a request which specifies the containing Return Authorization, and any quantity of Order Fulfillment Items within it which have been returned.
The whole Return Authorization doesn’t need to be confirmed at once - smaller subsets of Return Authorization Item quantities can be confirmed instead. The Return Confirmations created will be associated to those Return Authorization Items.
ReturnOperationEndpoint receives a ConfirmReturnRequest to confirm returned items
ReturnOperationService orchestrates the creation of Return Confirmations
ReturnProvider reads the Return Authorization for the confirmation
ConfirmReturnRequestValidator verifies that the confirmation is valid
The Return Authorization isn’t cancelled
The items being confirmed have enough pending quantity to be returned
ReturnConfirmationGenerationService generates the new Return Confirmations, one for each confirmed Return Authorization Item
Initial status should be PENDING
Calculate refundable amounts for confirmed quantity of Return Authorization Items
ReturnOperationService updates the Return Authorization’s status
If all items are fully confirmed, the status should be CONFIRMED
If not all items are fully confirmed, the status should be PARTIALLY_CONFIRMED
ReturnProvider persists the updated Return Authorization containing the new Return Confirmations in the OrderService
A Return Confirmed message is published, containing the request, the Return Authorization, order, and all the order’s fulfillments
Return the updated Return Authorization
At any point in the Return Authorization lifecycle, unless the return has been fully confirmed, it can be cancelled through the cancel endpoint using a request that only needs to specify the ID of the Return Authorization to cancel.
Whenever a Return Authorization is cancelled if it contains any items which were already confirmed, then those will be removed and placed into a new Return Authorization which will be marked as fully CONFIRMED.
ReturnOperationEndpoint receives a CancelReturnRequest to cancel a return
ReturnOperationService orchestrates the cancellation of the Return Authorization
ReturnProvider reads the Return Authorization to cancel
CancelReturnRequestValidator verifies that the return can be cancelled
The Return Authorization is either PENDING or PARTIALLY_CONFIRMED (not fully CONFIRMED or already CANCELLED)
If the Return Authorization contains any already-confirmed items, the ReturnSplittingService removes them and generates a new CONFIRMED Return Authorization to contain them
ReturnProvider persists both the cancelled Return Authorization and also the new confirmed Return Authorization, if applicable
A Return Cancelled message is published, containing the request, the cancelled Return Authorization, the split out confirmed Return Authorization (if applicable), order, and all the order’s fulfillments
Return a list containing both the cancelled Return Authorization and the confirmed Return Authorization (if applicable)
After a Return Confirmation has been created, a refund can be issued for it.
The PaymentRefundService handles going through the PENDING Return Confirmations within a Return Authorization and issues refunds based on a return item’s return type (refundable or not) and either estimated amounts to refund or overridden refund amount. After a Return Confirmation has been refunded, its status will change to COMPLETED.
|
Note
|
The return confirmation status can be changed to REFUND_AWAITING_RESULT if payment transaction results will be provided asynchronously. See Asynchronous Payment Transaction Support.
|
If there are multiple payments on the order, the chosen PaymentPriorityStrategy determines which should be refunded first. By default, payment types that are indicated as "Final Payments" will be refunded first - for example, a credit card will be refunded before a gift card.
This refunding can be triggered automatically through the PaymentRefundReturnConfirmedListener whenever a Return Confirmed event is received (see Auto Refund After Return is Confirmed configuration below).