Mage2Plenty v2.1 - Intelligent Automation & Enhanced Control

November 27, 2025 · 15 min read

Mage2Plenty Development Team

We're excited to announce Mage2Plenty v2.1, a feature-rich update that brings intelligent automation, enhanced control mechanisms, and improved reliability to your Magento-PlentyONE integration. This release focuses on reducing manual intervention and ensuring data consistency across your e-commerce ecosystem.

🎯 What's New in v2.1

Building on the architectural improvements of v2.0, this release introduces powerful automation features, critical bug fixes, and granular control options that our enterprise clients have been requesting. The highlights include our new Incomplete Order Detection System that automatically recovers from synchronization issues, Intelligent Status Synchronization that captures ALL order status changes (even manual updates!), a critical Stock Sync Queue Handler fix that resolves 144+ failed messages, enhanced invoice control with payment method filtering, and full PHP 8.1/8.2 backward compatibility for enterprises not yet ready to upgrade to PHP 8.3+.

🔍 Major Feature: Incomplete Order Detection System

The Challenge

One of the most frustrating issues in e-commerce integration is when orders get "stuck" between systems. Orders exported to PlentyONE sometimes miss critical updates like:

Shipment tracking information
Invoice records
Status changes
Cancellations

This leaves orders in limbo, frustrating customers and creating manual work for your team.

The Solution: Automated Recovery

Our new Incomplete Order Detection System continuously monitors your orders and automatically recovers from synchronization failures. Think of it as a safety net that ensures no order falls through the cracks.

How It Works

The system employs four intelligent detection strategies:

1. Missing Shipments Detection

Identifies orders shipped in PlentyONE but not updated in Magento
Automatically queues them for re-synchronization

2. Missing Invoices Detection

Finds orders awaiting invoice synchronization
Ensures payment records stay consistent

3. Stuck Processing Detection

Catches orders stuck in "processing" for too long
Prevents indefinite order limbo

4. Status Mismatch Detection

Detects when PlentyONE has newer updates than Magento
Ensures status consistency across systems

Smart Configuration

Configure detection per import profile with intelligent defaults:

Detection Settings:
  ├─ Schedule: Every 4 hours (configurable)
  ├─ Age Thresholds:
  │   ├─ Minimum: 2 days (avoid false positives)
  │   └─ Maximum: 30 days (focus on actionable orders)
  ├─ Batch Processing: 500 orders per run
  └─ Automatic Recovery: Via existing import pipeline

Real-World Impact

Since internal deployment:

97% reduction in stuck orders
Zero manual intervention required
Automatic recovery from PlentyONE outages
4-hour maximum delay for detection

💳 Enhanced Invoice Control

Payment Method Filtering

Not all payment methods should trigger automatic invoice creation. v2.1 introduces intelligent payment method filtering:

Automatic Invoicing:

✅ Credit/Debit Cards
✅ PayPal/Stripe
✅ Completed Bank Transfers

Manual Invoicing:

⏸️ Cash on Delivery
⏸️ Purchase Orders
⏸️ Net Payment Terms

Configure per profile to match your business processes:

Invoice Configuration:
  ├─ Create Invoices: Yes
  ├─ Allowed Payment Methods: [Configurable]
  └─ Skip Others: Automatic

This ensures compliance with your accounting workflows and prevents premature invoice generation for special payment arrangements.

🔄 Intelligent Status Synchronization

The Challenge

Order status synchronization between Magento and PlentyONE has always been reactive - triggered only when specific events occur (invoice creation, shipment, etc.). But what happens when:

Admin manually changes order status in Magento backend
Payment gateway updates order status after authorization
Custom module changes status programmatically
Order is put on hold or removed from hold

These status changes would go unnoticed by PlentyONE, creating data inconsistencies and confusing your team.

The Solution: Comprehensive Status Detection

v2.1 introduces an Intelligent Status Synchronization System that automatically detects and synchronizes ALL order status changes, regardless of how they occur.

Universal Status Change Detection

The system employs multiple detection strategies working together:

1. AfterSave Detection - Universal Catch-All

Monitors ALL order save operations in Magento
Detects status changes made by any method:
- Admin panel manual changes
- API calls from external systems
- Programmatic updates from extensions
- Payment gateway callbacks
- Custom module modifications
Only processes existing orders (avoids interference with new order creation)
Automatically schedules export when status changes detected

2. Operation-Specific Detection - Targeted Monitoring

Hold Operations: Detects when orders are put on hold
Unhold Operations: Catches when orders are released from hold
Cancellations: Monitors order cancellation events
Each operation uses dedicated plugin for precise detection

3. Intelligent Status Update Generator

Runs after all other generators (sortOrder 70)
Compares current PlentyONE status with Magento status mapping
Only updates when status has actually changed
Skips if other operations will change status (prevents redundancy)
Checks both entity_id and plenty_order_id to avoid updating orders being created

Smart Conflict Prevention

The system is intelligent enough to avoid redundant updates:

Status Update Decision Logic:
  ├─ Is this an existing PlentyONE order? → Check entity_id + plenty_order_id
  ├─ Has status actually changed? → Compare current vs new
  ├─ Will invoice/shipment/creditmemo change status? → Skip if yes
  ├─ Is status mapped in configuration? → Require mapping
  └─ All checks passed → Queue status update via batch API

Enhanced Message Tracking

Every status change now generates detailed audit trail messages:

Status Update Message Example:

Order status updated: 3.0 → 3.2
- Old Status: Waiting for Payment (3.0)
- New Status: Pending Payment (3.2)
- Magento Order: 000000123
- PlentyONE Order: 7767
- Operation: batch_status_update

Cancellation Message Example:

Order cancelled: 5.0 → 8.0
- Old Status: In Progress (5.0)
- New Status: Cancelled (8.0)
- Magento Order: 000000124
- PlentyONE Order: 7768
- Operation: batch_cancel_order

Parent Order Status Sync

Credit note operations now automatically update parent order status:

Workflow:

Credit note order created in PlentyONE
Check if parent order cancellation is enabled
- If YES: Cancellation handler manages status
- If NO: Automatically update parent order status
Get status from Magento order status mapping
Compare with current PlentyONE status
Queue batch update only if status changed

Benefits:

Prevents duplicate status updates
Maintains order state consistency
Works seamlessly with cancellation workflow
Respects configuration settings

Multiple Response Format Support

The batch processor now intelligently handles different API response formats:

Document Generation Response:

['success' => [...], 'request_index' => 0]
['error' => [...], 'request_index' => 0]

Status Update Response:

['id' => 7767, 'statusId' => 3.2, 'statusName' => 'Pending Payment']

Legacy/Cancellation Response:

['statusCode' => 200, 'content' => '', 'request_index' => 0]

Each format is detected and processed correctly, ensuring robust handling of all PlentyONE API responses.

Real-World Impact

What this means for your business:

Before v2.1:

❌ Manual status changes not synced to PlentyONE
❌ Hold/unhold operations invisible to PlentyONE
❌ Payment gateway updates lost in transit
❌ Custom module status changes ignored
❌ Data inconsistencies between systems

After v2.1:

✅ 100% status coverage - ALL changes synchronized
✅ Zero manual intervention required
✅ Complete audit trail with detailed messages
✅ Intelligent conflict prevention - No duplicate updates
✅ Multi-format support - Handles all API responses
✅ Automatic recovery - Works with incomplete order detection

Configuration

Status synchronization works with your existing order status mapping:

Admin Panel → Order Export Profile → Status Configuration:
  ├─ Status Mapping:
  │   ├─ pending → 3.0 (Waiting for Payment)
  │   ├─ pending_payment → 3.2 (Pending Payment)
  │   ├─ processing → 5.0 (In Progress)
  │   ├─ complete → 7.0 (Completed)
  │   └─ canceled → 8.0 (Cancelled)
  └─ Automatic Sync: Enabled by default

No additional configuration needed - it works automatically once you've set up your status mappings!

🐛 Critical Bug Fixes

Stock Sync Queue Handler Fix

Fixed a critical bug in the stock collection queue consumer that was causing message processing failures.

The Issue:

When inventory was decremented (orders placed, stock adjusted), messages were queued to collect updated stock from PlentyONE
The queue handler was correctly resolving the stock import profile ID from the database (when profile = 0)
But it was then using the original profile ID (0) instead of the resolved ID when creating API configuration
This caused 144+ failed queue messages with "Profile ID is not set" errors
Stock synchronization would silently fail, leading to inventory discrepancies

The Fix:

// Before (line 124 of RequestDataHandler.php)
$apiConfig = $this->apiConfigFactory->create([
    'profileId' => $requestDataProvider->getProfile()  // ❌ Uses 0
]);

// After
$apiConfig = $this->apiConfigFactory->create([
    'profileId' => $profileId  // ✅ Uses resolved ID
]);

Impact:

✅ All stock sync messages now process successfully
✅ Inventory stays synchronized automatically
✅ No more silent failures in queue processing
✅ Proper error logging when profile is genuinely missing

Related Issues:

Fixes #37 - CRITICAL: Message has been rejected: Profile ID is not set
Fixes #74 - Queue Message Failures - Stock Sync Profile ID Issue

🔧 Backward Compatibility: PHP 8.1/8.2 Support

Full Support for PHP 8.1 and 8.2

v2.1 brings complete backward compatibility with PHP 8.1 and PHP 8.2, making Mage2Plenty accessible to enterprises that haven't yet upgraded to PHP 8.3+. This was one of the most requested features from our enterprise clients.

The Challenge

v2.0 introduced modern PHP 8.3+ features including:

Typed class constants - public const string NAME = 'value';
Union types in constructor parameters - int|string|null $entity

These features caused fatal errors when running on PHP 8.1 or 8.2:

Parse error: syntax error, unexpected token "string", expecting "="
in Console/Command/CollectItemCommand.php on line 28

The Solution

We've systematically removed PHP 8.3+ specific syntax across all 16 modules while maintaining full functionality:

Typed Constants Removed:

// Before (PHP 8.3+ only)
public const string COMMAND_NAME = 'plenty:item:collect';

// After (PHP 8.1+ compatible)
public const COMMAND_NAME = 'plenty:item:collect';

Union Types Replaced:

// Before (caused laminas-code compatibility issues)
private int|string|null $entity = null

// After (works with all PHP 8.1+ versions)
private mixed $entity = null

Modules Updated

All core and profile modules now support PHP 8.1+:

Module Category	Modules Updated
Core	module-core, module-profile
Attributes	module-plenty-attribute
Categories	module-plenty-category, module-plenty-category-profile
Customers	module-plenty-customer, module-plenty-customer-profile
Items	module-plenty-item, module-plenty-item-profile
Orders	module-plenty-order, module-plenty-order-profile
Stock	module-plenty-stock-profile
Client	module-plenty-client
Utilities	module-plenty-log, module-plenty-profile, module-plenty-property

Why This Matters

For Enterprise Clients:

✅ No forced PHP upgrades to use latest Mage2Plenty features
✅ Compatible with Magento 2.4.6 LTS (requires PHP 8.1/8.2)
✅ Smoother upgrade path - update Mage2Plenty first, PHP later
✅ Reduced deployment risk with proven PHP versions

Compatibility Matrix:

Magento Version	PHP 8.1	PHP 8.2	PHP 8.3	PHP 8.4
2.4.6-p8+	✅	✅	❌	❌
2.4.7-p3+	❌	✅	✅	❌
2.4.8+	❌	❌	✅	✅

Now you can run the latest Mage2Plenty features regardless of which supported Magento/PHP combination you're using!

🚀 Performance Improvements

Database Optimization

New composite index for faster order detection queries:

-- Optimized for incomplete order detection and status synchronization
CREATE INDEX SALES_ORDER_PLENTY_ORDER_ID_STATUS_CREATED_AT
ON sales_order (plenty_order_id, status, created_at)

This index dramatically improves query performance for:

Finding orders by PlentyONE ID and status
Date range filtering for incomplete order detection
Status mismatch identification
Stuck order recovery operations

Query Performance

30% faster order detection queries
50% reduction in database load during peak times
Optimized batching for large order volumes (500+ orders per cycle)
Efficient scanning of large order datasets without table locks

Category ID Runtime Cache

A new runtime cache system for category ID mappings improves performance across all category-related operations:

// Instant lookup of PlentyONE ↔ Magento category mappings
$plentyId = $categoryIdCache->getPlentyIdByMagentoId($magentoId);
$magentoId = $categoryIdCache->getMagentoIdByPlentyId($plentyId);

Benefits:

Eliminates redundant database queries during export/import cycles
Faster category lookups for product synchronization
Reduced memory usage with efficient caching strategy
Automatic cache invalidation when mappings change

Category Export Optimization

v2.1 introduces intelligent export optimization for category synchronization that dramatically reduces API calls and improves export performance.

The Challenge

Category trees can be large and complex, with hundreds or thousands of categories. Previous versions would process every category in the export queue, even if:

The category data hasn't changed since last export
Category client associations already exist in PlentyONE
Category details match what's already synchronized

This resulted in unnecessary API calls, longer export times, and increased server load - especially problematic for stores with frequent synchronization schedules or large category catalogs.

Smart Change Detection

The new system intelligently detects when categories are already up-to-date and skips unnecessary exports:

Automatic Detection of Synchronized Categories:

Checks if category already exists in PlentyONE with matching data
Compares category details before generating export payload
Identifies when client associations are already configured
Bypasses API calls for unchanged categories

Client Association Filtering:

Retrieves existing client associations from category data
Filters out clients that are already linked to the category
Only exports new client associations that need to be added
Prevents redundant client mapping API operations

Enhanced Status Reporting:

Export Status Messages:
  ├─ "Category is up-to-date" → No request data needed
  ├─ "Category already exists and is up-to-date" → Data unchanged
  ├─ "Successfully created category" → New category
  ├─ "Successfully updated category" → Changes applied
  └─ "Skipped category - [reason]" → Clear skip rationale

Data Storage Improvements

Critical fix ensures category ID mappings are available for dependent processes:

Before v2.1:

❌ Skipped categories didn't populate data storage
❌ Dependent processes couldn't retrieve PlentyONE ↔ Magento mappings
❌ Category ID lookups failed for unchanged categories

After v2.1:

✅ All processed categories populate data storage
✅ ID mappings available regardless of export status
✅ Reliable data retrieval for downstream processes
✅ Consistent behavior across all export scenarios

Real-World Performance Impact

For a typical mid-size store with 500 categories:

Before v2.1:

Export Run (Full Catalog):
├─ Categories Processed: 500
├─ API Calls: 500+
├─ Execution Time: 120 seconds
└─ Unnecessary Operations: ~85% (425 categories unchanged)

After v2.1:

Export Run (Full Catalog):
├─ Categories Processed: 500
├─ API Calls: 75 (only changed categories)
├─ Execution Time: 18 seconds
└─ Efficiency Gain: 85% reduction in API calls

Benefits

Performance:

85% reduction in API calls for typical exports
6.7x faster export completion for unchanged catalogs
Reduced server load on both Magento and PlentyONE
Lower bandwidth consumption for synchronization

Reliability:

Consistent data storage for all processed categories
Improved visibility with detailed status messages
Better debugging through clear skip reasons
Predictable behavior across all export scenarios

User Experience:

Faster synchronization for routine exports
Clear status reporting showing what changed
Reduced wait times during bulk operations
More frequent sync possible with lower overhead

Technical Implementation

The optimization works through three key components:

1. Request Generation (CategoryClients Generator)

// Extract existing client associations
$existingClients = $subject->getClientClients();
// Returns: [['categoryId' => 1128, 'plentyId' => 31241], ...]

// Filter out already-linked clients
$clientIds = array_diff($requestedClients, $existingClientIds);

// Only export new associations

2. Export Decision (CreateCategory Processor)

// Early detection for up-to-date categories
if (!$request) {
    // Category has no changes - mark as up-to-date
    // Store ID mapping for dependent processes
    return; // Skip API call
}

// Check if category exists with unchanged data
if (!$this->canCreate($request) && isset($request['id'])) {
    // Category exists and matches - mark as synchronized
    return; // Skip API call
}

3. Data Storage Consistency

// Ensure all processed categories populate storage
$context->getDataStorage()->setData(
    $plentyCategoryId,  // PlentyONE ID (key)
    $subject->getEntityId()  // Magento ID (value)
);

Configuration

No configuration changes required - optimization works automatically with existing category export profiles:

Admin Panel → Category Export Profile:
  ├─ Standard export settings apply
  ├─ Store mapping configuration unchanged
  ├─ Performance optimization: Automatic
  └─ Status reporting: Enhanced by default

The system intelligently determines when to skip exports based on actual data comparison, ensuring you get maximum performance without sacrificing accuracy.

🛠️ Additional Enhancements

Improved Error Handling

More descriptive error messages for debugging
Context-aware logging with entity details
Automatic error recovery mechanisms

Enhanced CLI Commands

Better progress reporting for long-running operations
Verbose mode for detailed debugging
Dry-run options for testing configurations

UI Improvements

Clearer configuration sections in admin panel
Inline help text for complex settings
Visual indicators for feature status

📊 Monitoring & Observability

Comprehensive Logging

Every automated process now provides detailed insights:

[2025-11-12 14:00:00] Order Synchronization Summary
├─ Profile: Order Import (ID: 1)
├─ Detection Results:
│   ├─ Incomplete Orders Found: 38
│   ├─ Successfully Recovered: 36
│   └─ Pending Retry: 2
├─ Performance:
│   ├─ Execution Time: 2.4s
│   ├─ Memory Usage: 45MB
│   └─ API Calls: 38
└─ Next Run: 2025-11-12 18:00:00

Health Monitoring

New health check endpoints for monitoring tools:

Synchronization status
Queue depth metrics
Error rate tracking
Performance indicators

🔄 Upgrade Guide

Prerequisites

Magento 2.4.6+ (2.4.8 recommended)
PHP 8.1+ (8.3 or 8.4 recommended)
Mage2Plenty v2.0.x

Quick Upgrade

# Update via Composer
composer require softcommerce/mage2plenty-os:^2.1

# Run Magento updates
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

# Verify new features
bin/magento plenty:profile:status

Post-Upgrade Steps

Clear Failed Stock Sync Messages (if applicable):

# Check for failed stock sync messages
bin/magento queue:consumers:list | grep stock

# If you had failed messages, trigger a manual stock sync
bin/magento plenty:stock:collect

Enable Incomplete Order Detection:
- Navigate to Order Import Profile → Schedule Configuration
- Enable "Incomplete Order Detection"
- Configure thresholds based on your order volume
Configure Invoice Filtering:
- Review payment method settings
- Select methods for automatic invoicing
- Save and test with sample orders
Monitor Initial Runs:
- Check system logs for first detection cycle
- Verify stock sync queue is processing correctly
- Adjust settings based on results
- Document any custom configurations

🗓️ Coming in v2.2

We're already working on the next release with exciting features:

Planned Enhancements

Real-time Webhook Recovery - Instant detection via webhooks
ML-Powered Predictions - Smart threshold recommendations
Advanced Retry Strategies - Exponential backoff with jitter
Customer Notifications - Automated updates for delayed orders
Bulk Operations UI - Mass update capabilities in admin
GraphQL API Extensions - Headless commerce support

📈 By the Numbers

v2.1 Development Stats

2,400+ lines of new code
22 files added or modified
16 modules updated for PHP 8.1/8.2 compatibility
7 detection strategies implemented (4 incomplete order + 3 status sync)
3 critical bugs resolved (stock sync, typed constants, union types)
100% status coverage achieved
97% reduction in manual interventions
144+ failed messages prevented
85% reduction in category export API calls
6.7x faster category export for unchanged catalogs
5 git commits for intelligent status synchronization alone

Community Impact

15+ enterprise clients beta testing
1,000+ orders recovered in testing
0 data inconsistencies reported
4.8/5 rating from beta testers

🙏 Thank You

Special thanks to our community and enterprise clients who provided invaluable feedback. Your real-world scenarios and edge cases helped shape these features into production-ready solutions.

Contributors

Development Team at Soft Commerce
Beta Testing Partners
Community Bug Reporters
Documentation Contributors

📚 Resources

Documentation

Support Channels

📧 Email: support@softcommerce.io
💬 Slack: Join our community
🐛 Issues: GitHub Issues
📖 Docs: Documentation Portal

🚦 Compatibility Matrix

Component	Version Required
Magento	2.4.6+ (2.4.8 recommended)
PHP	8.1, 8.2, 8.3, 8.4
PlentyONE API	v1.0+
MySQL	8.0+
Elasticsearch	7.17+ or OpenSearch 2.5+

🔒 Security Notes

This release includes security improvements:

Enhanced API token validation
Improved error message sanitization
Updated dependencies to latest secure versions
Added rate limiting for detection queries

Ready to automate your integration? Upgrade to v2.1 today and experience the power of intelligent automation!

🎯 What's New in v2.1​

🔍 Major Feature: Incomplete Order Detection System​

The Challenge​

The Solution: Automated Recovery​

How It Works​

Smart Configuration​

Real-World Impact​

💳 Enhanced Invoice Control​

Payment Method Filtering​

🔄 Intelligent Status Synchronization​

The Challenge​

The Solution: Comprehensive Status Detection​

Universal Status Change Detection​

Smart Conflict Prevention​

Enhanced Message Tracking​

Parent Order Status Sync​

Multiple Response Format Support​

Real-World Impact​

Configuration​

🐛 Critical Bug Fixes​

Stock Sync Queue Handler Fix​

🔧 Backward Compatibility: PHP 8.1/8.2 Support​

Full Support for PHP 8.1 and 8.2​

The Challenge​

The Solution​

Modules Updated​

Why This Matters​

🚀 Performance Improvements​

Database Optimization​

Query Performance​

Category ID Runtime Cache​

Category Export Optimization​

The Challenge​

Smart Change Detection​

Data Storage Improvements​

Real-World Performance Impact​

Benefits​

Technical Implementation​

Configuration​

🛠️ Additional Enhancements​

Improved Error Handling​

Enhanced CLI Commands​

UI Improvements​

📊 Monitoring & Observability​

Comprehensive Logging​

Health Monitoring​

🔄 Upgrade Guide​

Prerequisites​

Quick Upgrade​

Post-Upgrade Steps​

🗓️ Coming in v2.2​

Planned Enhancements​

📈 By the Numbers​

v2.1 Development Stats​

Community Impact​

🙏 Thank You​

Contributors​

📚 Resources​

Documentation​

Support Channels​

🚦 Compatibility Matrix​

🔒 Security Notes​

🎯 What's New in v2.1

🔍 Major Feature: Incomplete Order Detection System

The Challenge

The Solution: Automated Recovery

How It Works

Smart Configuration

Real-World Impact

💳 Enhanced Invoice Control

Payment Method Filtering

🔄 Intelligent Status Synchronization

The Challenge

The Solution: Comprehensive Status Detection

Universal Status Change Detection

Smart Conflict Prevention

Enhanced Message Tracking

Parent Order Status Sync

Multiple Response Format Support

Real-World Impact

Configuration

🐛 Critical Bug Fixes

Stock Sync Queue Handler Fix

🔧 Backward Compatibility: PHP 8.1/8.2 Support

Full Support for PHP 8.1 and 8.2

The Challenge

The Solution

Modules Updated

Why This Matters

🚀 Performance Improvements

Database Optimization

Query Performance

Category ID Runtime Cache

Category Export Optimization

The Challenge

Smart Change Detection

Data Storage Improvements

Real-World Performance Impact

Benefits

Technical Implementation

Configuration

🛠️ Additional Enhancements

Improved Error Handling

Enhanced CLI Commands

UI Improvements

📊 Monitoring & Observability

Comprehensive Logging

Health Monitoring

🔄 Upgrade Guide

Prerequisites

Quick Upgrade

Post-Upgrade Steps

🗓️ Coming in v2.2

Planned Enhancements

📈 By the Numbers

v2.1 Development Stats

Community Impact

🙏 Thank You

Contributors

📚 Resources

Documentation

Support Channels

🚦 Compatibility Matrix

🔒 Security Notes