ForgeSync: A Ground-Up Sage 100 ERP Integration for Magento 2

Architecture & Design Principles

ForgeSync was built from scratch with a clear set of priorities:

Dependency Injection Only

Every class is wired through di.xml. No ObjectManager::getInstance() anywhere in the module. This makes the code predictable, testable, and aligned with Magento’s intended architecture.

Service Contracts

All business logic lives behind interfaces in Api/. Import services, export services, and the ERP client all have clean contracts, making it straightforward to swap implementations or mock dependencies in tests.

Plugin Architecture

Where we needed to modify core Magento behavior (pricing, product salability), we used plugins (interceptors), never preferences. This avoids class rewrites and plays nicely with other extensions.

Encrypted Credentials

API keys are stored using Magento’s EncryptorInterface and only decrypted at the point of use. No plaintext secrets in config or database.

What ForgeSync Does

The module manages bidirectional data synchronization between Magento and Sage 100 ERP across a wide surface area.

Inbound (ERP → Magento)

Scheduled imports pull data from the Sage API and persist it to dedicated fs_-prefixed tables:

• Customers & Addresses: full account sync with division/customer number mapping
• Items & Inventory: product catalog with real-time stock levels
• Price Codes: the foundation of B2B pricing
• Sales Orders & Lines: order history visible to customers on the frontend
• Invoices, Lines & Tracking: complete invoice history with shipment tracking
• Warehouses & Shipping Methods: operational data used in order routing

In total, 422,000+ records across 15 InnoDB tables, imported on a 2-hour cron cycle.

Outbound (Magento → ERP)

When a customer places an order, ForgeSync enqueues it for export. A separate cron (every 5 minutes) batches pending orders and pushes them to Sage via the API. The export handles:

• Customer resolution: matching Magento customers to Sage accounts via order attributes, customer EAV attributes, or configurable defaults
• Address mapping: bill-to and ship-to with full field translation
• Line items: SKU, quantity, pricing, with unit-of-measure handling
• Shipping method mapping: a dedicated fs_shipping_methods table maps Magento carrier/method codes to Sage shipping codes
• Tax schedule cascade: customer-level → ship-to-level → config default

CLI Interface

Every operation is available from the command line:

# Run all imports
php bin/magento forgesync:import

# Run a single import job
php bin/magento forgesync:import customers

# Export specific orders or enqueue by increment ID
php bin/magento forgesync:export --enqueue=100000042

B2B Pricing Engine

The most complex piece of ForgeSync is the pricing engine, a PHP reimplementation of a Sage stored procedure (spPriceCalculation).

B2B pricing in Sage is not simple. ForgeSync evaluates a 6-level price code cascade to determine which pricing rule applies to a given customer/product combination:

1. Customer + Item-specific price code
2. Customer + Product Line price code
3. Customer-level default price code
4. Item-specific default
5. Product Line default
6. Global fallback

Each resolved price code can use one of 6 pricing methods:

On top of that, each method supports 5-tier quantity breaks. Buy more, pay less.

There’s also a promotional pricing override layer that can temporarily replace any calculated price during a date window.

The pricing engine hooks into Magento via a frontend-scoped observer on catalog_product_get_final_price. It’s frontend-only by design. Running ERP pricing in admin or cron contexts would cause session-related issues and unnecessary overhead.

We verified the PHP implementation against the original stored procedure with exact-match test cases across all pricing methods and quantity tiers.

Admin Experience

Legacy integrations often leave store operators flying blind. ForgeSync includes three admin grids built with Magento’s UI Component framework:

All grids live under a dedicated ForgeSync menu with granular ACL resources (::queue, ::import, ::shipping_methods) for role-based access control.

Customer-Facing Features

ForgeSync extends the Magento customer account area with ERP data that B2B buyers actually need:

Each controller enforces ownership verification, so customers can only see records matching their ar_division_no and customer_no. Search filters and configurable cutoff periods keep the interface manageable for accounts with years of transaction history.

Testing

ForgeSync includes a unit test suite covering the three most critical services:

• PriceCalculationTest: 21 tests covering all 6 pricing methods, quantity breaks, promo overrides, and edge cases
• ImportServiceTest: 10 tests for record processing, error handling, and idempotency
• OrderExportTest: 9 tests for customer resolution, address mapping, and payload construction

php vendor/bin/phpunit --bootstrap vendor/autoload.php \
  app/code/Forgewise/ForgeSync/Test/Unit/Service/

We also built a mock API server (Node.js/Express) that reads from staging data and validates HMAC-SHA256 authentication, allowing full end-to-end testing without touching the production ERP.

Technical Decisions Worth Noting

A few choices that proved important during development:

Results

ForgeSync replaced a fragile legacy integration with a module that is:

The module handles the full lifecycle: importing master data, calculating complex B2B pricing in real time, exporting orders back to the ERP, and giving both admins and customers visibility into the process.