ForSURE.orders_data

Orders Data Module

Overview

The orders_data module provides comprehensive functionality for managing order-related data in the ForSURE SaaS platform. This module handles the complete lifecycle of order data, including orders, returns, fulfilment information, and manual data corrections.

Capabilities

The orders_data module offers the following core capabilities:

1. Orders Management (`orders/`)

Add Orders: Programmatically add orders via API with support for duplicate handling strategies
Retrieve Orders: Query and paginate through orders with advanced filtering (date range, search, source)
Upload Orders: Bulk upload orders from CSV or Excel files with profile-based mapping
Validate Orders: Pre-upload validation to check file format and data integrity

2. Returns Management (`returns/`)

Add Returns: Add return records with validation against existing orders
Retrieve Returns: Query returns with filtering and pagination capabilities
Upload Returns: Bulk upload returns from files with error handling
Validate Returns: Check return files before upload for data quality

3. Fulfilment Management (`fulfilment/`)

Retrieve Fulfilment: Query fulfilment/packaging data with filtering
Upload Fulfilment: Upload fulfilment data from files
Fulfilment Algorithm: Run custom fulfilment algorithms for specific orders
Validate Fulfilment: Pre-upload validation of fulfilment files

Key Features

Error Handling Strategies

The module supports flexible error handling for data operations:

SKIP: Silently ignore errors/duplicates
WARN_AND_SKIP: Report errors but continue processing
WARN_AND_ADD: Report errors but still add valid records
RAISE: Stop processing and raise an error

Data Validation

Automatic date format detection and conversion
Duplicate detection and handling
Cross-reference validation (e.g., returns must reference existing orders)
Quantity validation (e.g., returns cannot exceed order quantities)

File Upload Support

CSV and Excel file formats
Profile-based column mapping
Multiple file uploads in a single request
Background processing for large uploads

Query Capabilities

Date range filtering
Free-text search across string columns
Source-based filtering
Pagination with configurable limits
Grouped results (e.g., orders grouped by order ID)

Authentication & Authorization

All endpoints require authentication and specific role-based permissions:

ORDERS_VIEW: View orders and fulfilment data
ORDERS_ADD: Add/upload orders and fulfilment data
ORDERS_ADMIN: Manage manual changes
RETURNS_VIEW: View returns data
RETURNS_ADD: Add/upload returns data

Usage Examples

Adding Orders via API

Orders can be added programmatically using a JSON payload with order details. The API supports batch operations and configurable duplicate handling.

{
    "orders": [
        {
            "sku": "481769825",
            "title": "Example Product",
            "orderid": "FS1234",
            "quantity": 1,
            "date": "2024-01-27T22:16:25.365Z",
            "country": "NL",
            "postal_code": "1234AB",
            "b2b": false
        }
    ],
    "duplicates": "WARN_AND_SKIP"
}

Querying Data

All data types (orders, returns, fulfilment) can be queried with pagination and filtering options including date ranges, search terms, and source filtering. Results are grouped appropriately for easy navigation.

Uploading Data 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.

Best Practices

Always validate files using the /check endpoints before uploading
Use appropriate error handling strategies based on your use case
Set up profiles correctly to ensure proper column mapping
Monitor background tasks for large file uploads
Use manual changes sparingly and document the reason for changes
Filter by source when querying to track data origins