Flow Name: Return Item¶

Last Updated: 2025-10-22 Source Code: Return_Item.flow-meta.xml

API Name: Return_Item Status: Active Type: Modified Standard Trigger: Screen Flow - Manual launch from Order Summary pages

Business Purpose¶

This comprehensive multi-stage wizard flow handles the complete return and refund process for order items after fulfillment. It guides users through item selection, quantity and reason specification, fee calculations, and final submission for returns.

Process Flow¶

Stage 1: Select Items¶

• Displays available order items for return
• Shows product names, status, quantities available, and line totals
• Users select which items to return from the order summary

Stage 2: Select Quantities and Reasons¶

• Users specify quantities to return for each selected item
• Capture return reasons for each item
• Validates quantities are within available limits

Stage 3: Select Products with Return Fees (Conditional)¶

• Only appears if return fees are configured/allowed
• Users select additional fee products to apply if applicable
• Optional stage based on business configuration

Stage 4: Select Return Fees Amounts (Conditional)¶

• Configure return fee amounts and descriptions
• Only appears if fees were selected in Stage 3
• Allows customization of fee amounts

Stage 5: Review and Submit¶

• Preview the complete return request before submission
• Shows summary of items, quantities, fees, and total refund amount
• Final validation before processing

Stage 6: Confirm and Finish¶

• Processes return request through Order Management APIs
• Creates credit memos for returned items
• Processes refunds and updates order status
• Displays confirmation to user

flowchart TD
    Start([Start: User Launches<br/>Return Item Flow]) --> Validate{Order Summary<br/>Managed?}

    Validate -->|No| ShowError[Display Error:<br/>Unmanaged Orders]
    ShowError --> End([End])

    Validate -->|Yes| Stage1[Stage 1:<br/>Select Items to Return]
    Stage1 --> Stage2[Stage 2:<br/>Enter Quantities and Reasons]

    Stage2 --> CheckFees{Return Fees<br/>Allowed?}
    CheckFees -->|Yes| Stage3[Stage 3:<br/>Select Fee Products]
    Stage3 --> Stage4[Stage 4:<br/>Configure Fee Amounts]
    Stage4 --> Stage5[Stage 5:<br/>Review and Submit]

    CheckFees -->|No| Stage5
    Stage5 --> Stage6[Stage 6:<br/>Process Return]

    Stage6 --> CreateProduct[Create Fee Products<br/>if Needed]
    CreateProduct --> Preview[Preview Return<br/>Impact via API]

    Preview --> Submit[Submit Return Request<br/>via API]
    Submit --> CreateInvoice[Create Invoice<br/>for Fees if Applicable]

    CreateInvoice --> CreateCredit[Create Credit Memo<br/>for Return]
    CreateCredit --> ProcessRefund[Process Refund<br/>Async]

    ProcessRefund --> CheckComplete{All Items<br/>Returned?}
    CheckComplete -->|Yes| CancelOrder[Cancel<br/>Order Summary]
    CheckComplete -->|No| UpdateStatus[Update Order<br/>Status]

    CancelOrder --> Confirm[Display<br/>Confirmation]
    UpdateStatus --> Confirm
    Confirm --> End

    style Start fill:#e1f5ff
    style Validate fill:#fff4e1
    style ShowError fill:#ffcccc
    style Stage1 fill:#e1ffe1
    style Stage2 fill:#e1ffe1
    style CheckFees fill:#fff4e1
    style Stage3 fill:#e1ffe1
    style Stage4 fill:#e1ffe1
    style Stage5 fill:#e1ffe1
    style Stage6 fill:#ffe1e1
    style CreateProduct fill:#ffe1e1
    style Preview fill:#f0e1ff
    style Submit fill:#ffe1e1
    style CreateInvoice fill:#ffe1e1
    style CreateCredit fill:#ffe1e1
    style ProcessRefund fill:#ffe1e1
    style CheckComplete fill:#fff4e1
    style CancelOrder fill:#ffe1e1
    style UpdateStatus fill:#ffe1e1
    style Confirm fill:#e1ffe1
    style End fill:#e1f5ff

Key Business Rules¶

• Only processes managed Order Summaries (not unmanaged orders)
• Validates items are available for return before processing
• Dynamically creates Product2 and PriceBookEntry records for return fees if they don't exist
• Tracks return counts vs. original item counts to determine order cancellation
• Automatically cancels Order Summary if all items are returned
• Uses async refund processing through ensureRefundsOrderSummaryAsync
• Creates platform events to trigger refund workflows
• Implements six-stage wizard for user-guided return process

Dependencies¶

• Salesforce Order Management licenses and configuration
• Order Summary and Order Item Summary objects properly configured
• Payment gateway integration for refund processing
• Email templates for return notifications (if configured)
• Platform events for refund workflow triggers
• Product2 and PriceBookEntry objects for fee management

Changes¶

Order Management template flow for return processing.

Pre-Go-Live Concerns¶

CRITICAL - Fix Before Go-Live¶

• Add comprehensive rollback mechanisms for partial failures across the multi-stage transaction
• Implement validation to prevent dynamic Product2 creation from creating duplicate fee products
• Add transaction boundary management to ensure atomicity of return operations
• Validate that payment gateway supports async refund processing

HIGH - Address Soon After Go-Live¶

• Add enhanced error handling for all Order Management API calls (preview, submit, invoice, credit memo, refund)
• Implement monitoring for async refund processing completion
• Add validation for fee calculations to prevent incorrect refund amounts
• Create reconciliation process for return counts vs. actual returns

MEDIUM - Future Enhancement¶

• Add audit trails for all financial operations (returns, refunds, fee applications)
• Implement business rules for maximum return quantities and timeframes
• Add support for partial refunds and restocking fees configuration
• Create admin tools for managing stuck or failed returns
• Add comprehensive logging for troubleshooting complex return scenarios

LOW - Monitor¶

• Track return and refund success rates
• Monitor for returns with incomplete refund processing
• Alert on orders with count discrepancies
• Dashboard for return volume, reasons, and financial impact
• Monitor dynamic product creation for fee products

Maintenance Notes¶

• Complexity: Very High - multi-stage wizard with complex financial operations and OMS integration
• Screen flow with six stages requires careful navigation and state management
• Heavy dependency on Order Management APIs creates integration complexity
• Dynamic product creation for fees requires careful data management
• Async refund processing creates potential race conditions and timing issues
• Variables: selectedOrderItem, changeItemsWithFees, originalItemsCount, returnedItemsCount, selectedFeeDescription
• Review quarterly to ensure return policies align with flow configuration
• Test thoroughly for all return scenarios including partial returns, full returns, and fee applications
• Coordinate with finance team on return fee structures and refund processing requirements