ForSURE.orders_data.orders

Orders Module

Overview

The orders module provides comprehensive functionality for managing order data in the ForSURE SaaS platform. It handles the complete lifecycle of orders, from adding individual orders via API to bulk uploading from files, with robust validation and error handling.

Features

Order Management Capabilities

  1. Add Orders Programmatically

    • Add orders via JSON API with structured data
    • Support for flexible duplicate handling strategies
    • Automatic validation of required fields
    • Support for both B2B and B2C orders

  2. Retrieve and Query Orders

    • Paginated order 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 orders 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

Order Fields

Required Fields:

  • sku (str): Product SKU identifier
  • title (str): Product title/name
  • orderid (str): Unique order identifier
  • quantity (int): Number of items ordered
  • date (datetime): Order date in ISO format
  • country (str): Country code (e.g., "NL")
  • postal_code (str): Postal/ZIP code
  • b2b (bool): Whether this is a business-to-business order

Optional Fields:

  • company_name (str): Company name for B2B orders
  • total_weight (float): Total weight of the order
  • packaging_weight (float): Weight of packaging

Error Handling

The module supports flexible error handling strategies:

  • SKIP: Silently ignore duplicates/errors
  • WARN_AND_SKIP: Report issues but continue (default)
  • RAISE: Stop processing and raise an error

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 Orders

Orders 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 Orders 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

  • ORDERS_VIEW: Required to retrieve orders
  • ORDERS_ADD: Required to add or upload orders

Best Practices

  1. Always validate files using the validation endpoint before uploading
  2. Use appropriate duplicate handling based on your use case
  3. Set up profiles correctly to ensure proper column mapping
  4. Monitor background tasks for large file uploads
  5. Use date filters when querying to improve performance
  6. Track sources using fileId to maintain data lineage

Integration

The orders module integrates with:

  • Volumes: Automatic volume refresh after upload
  • Manual Changes: Supports manual corrections via the changes module
  • Reports: Provides data for reporting and analytics
  • Categorylist: Links orders to product catalog

File Upload Process

  1. Validation: Files are validated synchronously
  2. Processing: Valid files are processed in the background
  3. Volume Refresh: Order volumes are automatically refreshed
  4. Error Handling: Errors are reported per file

Response Format

Successful Order Addition

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

Paginated Order Response

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