Returns Module

Overview

The returns module manages return data for orders. It tracks returned items, validates returns against existing orders, and ensures data integrity through quantity validation and order reference checking.

Features

Returns Management Capabilities

1. Add Returns Programmatically

   • Add returns via JSON API with structured data
   • Support for multiple error handling strategies
   • Automatic validation against existing orders
   • Quantity validation to ensure returns don't exceed order quantities

2. Retrieve and Query Returns

   • Paginated returns retrieval with configurable page sizes
   • Advanced filtering by date range, search terms, and data source
   • Results grouped by order ID for easy navigation
   • Free-text search across all string columns

3. Bulk Upload from Files

   • Upload returns from CSV or Excel files
   • Background processing for large file uploads
   • Profile-based column mapping for flexible file formats
   • Support for multiple file uploads in a single operation

4. File Validation

   • Pre-upload validation to catch errors early
   • Column mapping verification against configured profiles
   • Data format checking and validation
   • Detailed error reporting for troubleshooting

Data Model

Return Fields

Required Fields:

• orderid (str): Order ID that this return is associated with
• sku (str): Product SKU identifier
• quantity (int): Number of items returned
• return_date (datetime): Return date in ISO format

Error Handling

The module supports flexible error handling for different scenarios:

Duplicate Handling

• SKIP: Silently ignore duplicate returns
• WARN_AND_SKIP: Report duplicates but skip them (default)
• WARN_AND_ADD: Report duplicates but still add them
• RAISE: Raise an error and stop processing

Order Missing Handling

• SKIP: Silently ignore returns without matching orders
• WARN_AND_SKIP: Report but skip (default)
• WARN_AND_ADD: Report but still add
• RAISE: Raise an error and stop

Negative Quantity Handling

• SKIP: Silently ignore returns exceeding order quantity
• WARN_AND_SKIP: Report but skip (default)
• WARN_AND_ADD: Report but still add
• RAISE: Raise an error and stop

Validation Rules

1. Order Reference: Return must reference an existing order
2. Quantity Validation: Returned quantity cannot exceed ordered quantity
3. Duplicate Detection: Based on (orderid, organization, sku) combination

Usage Examples

Adding Returns via API

Returns can be added programmatically using a JSON payload with return details. The API supports batch operations and configurable error handling for duplicates, missing orders, and quantity validation.

{
    "returns": [
        {
            "orderid": "FS1234",
            "sku": "481769825",
            "quantity": 2,
            "return_date": "2024-01-27T22:16:25.365Z"
        }
    ],
    "duplicates": "WARN_AND_SKIP",
    "order_missing": "WARN_AND_SKIP",
    "negative_quantity": "WARN_AND_SKIP"
}

Querying Returns

Returns can be retrieved with pagination and filtering options including date ranges, search terms, and source filtering. Results are grouped by order ID for easy navigation.

Uploading Returns from Files

Bulk uploads support CSV and Excel formats with profile-based column mapping. Multiple files can be uploaded simultaneously, each with its own profile and source identifier.

Permissions

• RETURNS_VIEW: Required to retrieve returns
• RETURNS_ADD: Required to add or upload returns

Best Practices

1. Always validate files using the validation endpoint before uploading
2. Use appropriate error handling based on your use case
3. Ensure orders exist before adding returns
4. Validate quantities to prevent negative quantities
5. Track sources using fileId for data lineage
6. Use date filters when querying to improve performance

Integration

The returns module integrates with:

• Orders: Validates returns against existing orders
• Manual Changes: Supports manual corrections
• Reports: Provides return data for analytics and compliance

File Upload Process

1. Validation: Files are validated synchronously
2. Processing: Valid files are processed in the background
3. Order Validation: Returns are validated against existing orders
4. Quantity Validation: Quantities are checked against order quantities
5. Error Handling: Errors are reported per file

Response Format

Successful Return Addition

{
    "status": "success",
    "duplicates": [],
    "order_missing": [],
    "negative_quantity": []
}

Response with Warnings

{
    "status": "success",
    "duplicates": [],
    "order_missing": [],
    "negative_quantity": [
        {
            "orderid": "FS1234",
            "sku": "481769825",
            "quantity": 2,
            "return_date": "2024-01-27T22:16:25.365000Z"
        }
    ]
}

Paginated Returns Response

{
    "items": [...],
    "source_names": ["source1", "source2"],
    "total": 150,
    "limit": 50,
    "offset": 0,
    "next_offset": 50,
    "prev_offset": null
}

Common Use Cases

1. Return Processing: Track customer returns for refunds/exchanges
2. Inventory Reconciliation: Adjust inventory based on returns
3. Compliance Reporting: Report returns for regulatory compliance
4. Analytics: Analyze return rates and patterns