Mage2Plenty v3.0 - New Product Export Engine & Order Improvements
We're excited to announce Mage2Plenty v3.0, a major release introducing a completely redesigned Product Export Engine built from the ground up for performance and reliability. This release also brings credit memo import with custom refund amounts, configurable order export retry, and important fixes across 10 modules.
What's New in v3.0
This release is centered around a new command-based product export architecture that replaces the legacy Generator/Processor pipeline. Alongside this, we've improved order handling with partial refund support, configurable retry limits, and better error notifications.
New Product Export Engine
Complete Architecture Redesign
The product export has been rebuilt using a modern Command/Collector/Executor pipeline that collects all export operations first, then executes them in optimized batches:
Export Pipeline:
1. COLLECT - Data builders generate commands per product
2. BATCH - Smart strategy groups commands by type
3. EXECUTE - Batch API calls (up to 100 variations per request)
4. PROCESS - Save results and update mappings
Why This Matters:
The old architecture processed products one at a time, making a separate API call for each. The new engine collects commands across all products and batches them together, dramatically reducing API calls.
| Scenario | Old Architecture | New Architecture |
|---|---|---|
| 10 simple products | 10 API calls | 1 API call |
| 100 simple products | 100 API calls | 1 API call |
| 50 configurables (200 variations) | 50 API calls | 2 API calls |
Smart Change Detection
Every data builder compares the desired state against existing PlentyONE data. If a variation is already up-to-date, it's skipped entirely - no API call needed.
Supported data types with change detection:
- Core data - status, name, number, external ID
- Prices - sales prices, purchase prices (2 decimal precision)
- Barcodes - GTIN, UPC, EAN, ISBN
- Categories - assignments with position and inheritance
- Properties - selection, global, and language-scoped values
- Images - MD5 checksum comparison, upload and assignment
- Dimensions - weight, width, length, height
- Tax - VAT ID mapping
- Client - webstore assignments
Automatic Dependency Resolution
Pre-processors ensure all dependencies exist in PlentyONE before the export begins:
Pre-Processors:
├─ CategoryPreProcessor - Creates missing categories
├─ PropertyPreProcessor - Creates missing properties
└─ AttributePreProcessor - Creates missing configurable attributes
Properties and their selection values are now saved to the local database immediately after creation, so they're available for the product export without waiting for async queue processing.
CLI Improvements
The plenty:item:export command now supports:
- Dry-run mode (
-d) - Preview what would be exported without making changes - SKU filtering (
-s SKU1,SKU2) - Export specific products - Status filtering (
-w pending) - Export by queue status - Real-time progress bar - Per-product progress during command collection and batch execution
# Preview export for specific SKUs
bin/magento plenty:item:export -s "SKU-001,SKU-002" -d
# Export only pending queue items
bin/magento plenty:item:export -w pending
Parent Product Auto-Resolution
When a child product is added to the export queue, the system now automatically resolves and includes its parent configurable product, ensuring complete product structures are always exported together.
Credit Memo Import with Custom Amounts
Partial Refund Support
The order import now supports credit memos with custom refund amounts, allowing partial refunds that don't match the original order line amounts:
Credit Memo Import:
├─ Custom item amounts - Refund partial item values
├─ Shipping refund - Include shipping in refund
├─ Credit note validation - Requires credit note order type
└─ Zero-quantity handling - Fixed null return for zero-qty items
This addresses a common real-world scenario where customer service issues partial refunds through PlentyONE that need to be reflected accurately in Magento.
Configurable Order Export Retry
Replace Hardcoded Retry with Configurable Limits
Previously, failed order exports retried indefinitely within a 12-hour window. Now you can configure:
- Maximum retry attempts (default: 3) - Stop retrying after N failures
- Email notifications - Get alerted when retries are exhausted
- Unreliable lookup removed - External order lookup on failure removed due to PlentyONE indexing delays
Retry Configuration:
├─ retry_max_attempts: 3 # Configurable in profile
├─ retry_notification_enabled: Yes # Email on exhaustion
└─ Centralized via ProfileNotification service
Order Integrity Check
The duplicate order detection system has been renamed and enhanced into a full Order Integrity Check service:
- Unified service architecture replacing scattered detection logic
- CLI command with skip flags instead of opt-in for more intuitive usage
- Migrated email notifications to the centralized ProfileNotification service
Additional Improvements
API Client
- Sensible default timeouts - Connection: 60s, Request: 120s (previously unlimited when unconfigured)
Attribute Export
- Immediate data persistence - Attribute data saved immediately after export to PlentyONE, available for subsequent operations without queue delay
- Simplified cache reset - Full-clear only, removing unused selective reset complexity
Property Export
- Immediate data availability - Property data (including selections and values) saved to local DB right after export
- Skip redundant exports - Property groups already existing in PlentyONE are no longer re-exported
- Shared REST API interfaces - Unified property group collection using shared interfaces
Admin Notifications
- Email notification service - New centralized service for sending admin alert emails
- Order export retry alerts - Automatic email when retry attempts are exhausted
Compatibility
- PHP 8.4 - Fixed
gc_collect_cycles()compatibility in batch message aggregation - Magento 2.4.8 - Verified compatibility across all modules
Upgrade Guide
Prerequisites
- Magento 2.4.6+ (2.4.8 recommended)
- PHP 8.1+ (8.3 or 8.4 recommended)
- Mage2Plenty v2.3.x
Quick Upgrade
# Update via Composer
composer require softcommerce/mage2plenty-os:^3.0
# Run Magento updates
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
Post-Upgrade Steps
- Review Order Export Retry Settings - The new configurable retry defaults to 3 attempts. Adjust in your order export profile if needed.
- Test Product Export - Run a dry-run to verify the new engine works with your catalog:
bin/magento plenty:item:export -s "YOUR-SKU" -d - Configure Notifications - Enable email notifications for order export retry exhaustion if desired.
Updated Modules
| Module | Version | Key Changes |
|---|---|---|
| module-plenty-item-profile | 3.0.0 | New product export engine |
| module-plenty-item | 2.3.0 | Parent product resolution, data providers |
| module-core | 2.3.0 | Email notification service |
| module-plenty-order-profile | 2.4.0 | Credit memo import, configurable retry |
| module-plenty-order | 2.0.4 | Zero-quantity fix, API client improvements |
| module-plenty-attribute | 2.0.2 | Immediate data persistence after export |
| module-plenty-client | 2.1.1 | Default API timeouts |
| module-plenty-profile | 2.1.1 | System property setup improvements |
| module-plenty-property | 2.0.3 | Immediate save, skip redundant groups |
| module-profile-notification | 2.0.1 | Admin notification formatting |
What's Next
v3.1 Preview:
- Dedicated PIM endpoints for relation entities (properties, prices, categories)
- Pagination support for large catalog exports
- Incomplete product export prevention
- Remaining data builders (unit, supplier, warehouse)
Resources
Ready to supercharge your product exports? Upgrade to v3.0 today!