Fulfilment Module

Overview

The fulfilment module manages packaging and fulfilment data for orders. It tracks packaging dimensions, weights, box IDs, and other fulfilment-related information that is essential for compliance reporting and logistics management.

Features

Fulfilment Management Capabilities

1. Retrieve Fulfilment Data

   • Paginated fulfilment 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

2. Bulk Upload from Files

   • Upload fulfilment data 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

3. Fulfilment Algorithm

   • Apply custom fulfilment algorithms to determine optimal packaging
   • Automatically calculate packaging based on order contents and weights
   • Integration with categorylist for available box types
   • Requires special access attribute for custom algorithm execution

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

Fulfilment Fields

Key Fields:

• orderid (str): Order identifier (primary key)
• dimension (str): Package dimensions in format "HxWxD"
• fulfilmentday (datetime): Fulfilment date
• total_weight (float): Total weight of the package
• main_type (str): Main packaging type
• main_type_weight (float): Weight of main packaging type
• box_id (str): Box identifier (maps to categorylist SKU)
• source (str): Source/file name
• profile (int): Profile ID for column mapping
• error (str): Error message if processing failed

Fulfilment Algorithm

The fulfilment algorithm can automatically determine optimal packaging for orders based on:

• Order contents and weights
• Available box types from categorylist
• Custom fulfilment rules (if user has access)

Access Control

To run custom fulfilment algorithms, users need the access-fulfilment-algorithm attribute.

Usage Examples

Retrieving Fulfilment Data

Fulfilment data can be retrieved with pagination and filtering options including date ranges, search terms, and source filtering. Results are grouped by order ID.

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

Running Fulfilment Algorithm

The fulfilment algorithm can be executed for specific orders to automatically determine optimal packaging based on order contents, weights, and available box types from the categorylist.

Permissions

• ORDERS_VIEW: Required to retrieve fulfilment data
• ORDERS_ADD: Required to upload fulfilment or run algorithms

Best Practices

1. Validate files using the validation endpoint before uploading
2. Ensure box_id mapping to categorylist for proper categorization
3. Use consistent dimension format (HxWxD)
4. Track sources using fileId for data lineage
5. Run algorithms after uploading fulfilment data for optimal packaging

Integration

The fulfilment module integrates with:

• Orders: Links fulfilment to order data
• Categorylist: Maps box_id to product catalog
• Manual Changes: Supports manual corrections
• Reports: Provides packaging data for compliance reporting

File Upload Process

1. Validation: Files are validated synchronously
2. Processing: Valid files are processed in the background
3. Algorithm Application: Custom algorithms can be applied if enabled
4. Error Handling: Errors are reported per file

Response Format

Paginated Fulfilment Response

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

Algorithm Run Response

{
    "status_code": 200
}

Dimension Format

Dimensions should be provided in the format: "HxWxD" where:

• H = Height
• W = Width
• D = Depth

Example: "10x20x15" represents 10cm height, 20cm width, 15cm depth.