Magento 2

The Omnium Magento 2 integration provides bidirectional synchronization between Omnium OMS and Adobe Commerce/Magento 2. This integration enables e-commerce order management with full support for product synchronization, inventory management, customer sync, and order status updates.

Overview

The integration supports:

• Order Import: Imports orders from Magento to Omnium for fulfillment
• Order Export: Updates order status, invoices, and shipments back to Magento
• Product Import: Imports products from Magento (simple, configurable, and bundle products)
• Product Export: Exports product data and prices to Magento
• Inventory Export: Synchronizes stock levels from Omnium to Magento
• Customer Sync: Imports customer data from Magento to Omnium

Architecture

┌─────────────┐                    ┌─────────────────┐
│   Omnium    │◄──────────────────►│   Magento 2     │
│     OMS     │   REST API         │                 │
└─────────────┘                    └─────────────────┘
      │                                    │
      │ ┌─────────────────────────────────┐│
      │ │  Data Flows:                    ││
      │ │  ← Orders (import)              ││
      │ │  → Order status (export)        ││
      │ │  ← Products (import)            ││
      │ │  → Products/Prices (export)     ││
      │ │  → Inventory (export)           ││
      │ │  ← Customers (import)           ││
      │ └─────────────────────────────────┘│
      ▼                                    ▼

Configuration

Connector Options

The Magento integration is configured via connector options in the tenant settings. Add a connector with the name Magento.

Order Import/Export Properties

Product Import/Export Properties

Inventory Export Properties

Property Mapping (Product Export)

Map Omnium product fields to Magento custom attributes using map_ prefixed properties:

Example configuration:

{
  "Properties": [
    { "Key": "map_Brand", "Value": "manufacturer" },
    { "Key": "map_Color", "Value": "color" },
    { "Key": "map_Size", "Value": "size" }
  ]
}

Market Configuration

For multi-store Magento setups, configure markets with Magento store codes:

Store Configuration

Order Import

Orders are imported from Magento via the MagentoOrderScheduledTask. The scheduler polls Magento for orders changed since the last sync.

Import Flow

1. Scheduled task queries Magento for orders updated since last sync (minus 10 minutes buffer)
2. Orders are paginated and fetched in batches of 100
3. Each Magento order is mapped to an Omnium order
4. New orders with status New or PaymentReview are processed through the order workflow
5. Existing orders are updated if not already in a progressed state

Order Status Mapping

Payment Mapping

The integration maps various payment methods automatically:

Shipping Integration

The integration supports multiple shipping providers:

• Ingrid: Reads TOS ID, carrier, location from extension attributes
• Klarna Shipping Assistant: Reads delivery details from Klarna extensions
• Porterbuddy: Fetches tracking number from Magento shipments
• Service Points: Extracts service point ID from shipping method name

Order Properties

Order Export

Orders are exported to Magento when workflow triggers.

Export Operations

Export Flow

1. Order reaches export workflow step
2. Exporter checks which operations are enabled
3. For invoice: Calls POST /V1/order/{id}/invoice
4. For ship: Calls POST /V1/order/{id}/ship
5. For status: Calls order status update endpoint
6. Success/failure tracked via order properties

Export Properties

Product Import

Products are imported from Magento via scheduled tasks that support both delta and full imports.

Scheduled Tasks

Import Flow

1. Task queries Magento for products changed since last sync
2. Configurable products and their variants are processed together
3. Simple products are identified as standalone or variants based on visibility
4. Products are enriched with existing Omnium data and saved

Product Type Handling

Field Mapping

Custom Attribute Mapping

Product Export

Products are exported to Magento when Omnium is the master system (IsOmniumMasterForProducts=true).

Export Flow

1. Products trigger export via scheduled task or manual action
2. Products are mapped to Magento format with configured attribute mappings
3. Products are grouped by market/store view
4. Batch PUT requests update products in Magento
5. Configurable product links are created for parent-child relationships

Mapping Configuration

Use map_ prefixed properties to map Omnium fields to Magento attributes:

{
  "Properties": [
    { "Key": "map_Brand", "Value": "manufacturer" },
    { "Key": "map_VariantParentId", "Value": "parent_sku" },
    { "Key": "map_Color", "Value": "color" },
    { "Key": "map_Size", "Value": "size" }
  ]
}

Website Assignment

Products are assigned to Magento websites based on store configuration:

• Store must have magentoStoreId property set
• Product must be assigned to the store in Omnium

Inventory Export

Inventory is exported from Omnium to Magento.

Export Methods

Single Source (Legacy)

• Uses PUT /V1/products/{sku}/stockItems/{itemId}
• Requires IsInventoryExportOnlyForPrimaryWarehouses=true
• Only exports inventory for primary warehouses

Multi-Source Inventory (MSI)

• Uses POST /V1/inventory/source-items
• Supports multiple warehouses/sources
• Each store maps to a Magento source via MagentoSourceCode external ID

Export Flow

1. Inventory change triggers export
2. Store is validated (must be warehouse, not excluded)
3. Source code is resolved from store external ID or store ID
4. Available quantity is calculated
5. Source item is posted to Magento with status (1=in stock, 0=out of stock)

Configurable Product Stock

When a variant comes back in stock, the exporter also checks if the configurable (parent) product needs its stock status updated.

Scheduled Task

Customer Sync

Customers are imported from Magento via the MagentoCustomersScheduledTask.

Import Flow

1. Task queries Magento for customers changed since last sync
2. Customers are matched by email address
3. New customers are created in Omnium
4. Customer club memberships are synchronized

Field Mapping

External IDs

Customer Club Integration

The MagentoCustomerClubService synchronizes customer group memberships with Omnium customer clubs using the MagentoCustomerClubGroupId property.

Scheduled Tasks

External IDs and Properties

External ID Providers

Order Properties

Product Properties

Payment Provider Integration

Klarna

• Transaction ID extracted from status history
• Klarna reference stored in KlarnaReference property
• Delivery details read from extension attributes

Svea (Swish/Trustly)

• Payment type determined from svea_payment_method extension
• Direct capture automatically added for Swish and Trustly payments

Vipps

• Transaction ID can use order increment ID (IsVippsTransactionOrderId=true)

Gift Cards

• FrontSystems gift cards: Enable via IsFrontSystemGiftCardEnabled
• AW Gift Cards: Automatically detected from extension attributes

Workflow Integration

Order Import Workflow

Orders from Magento automatically enter the configured order workflow. The PaymentReview status marks orders as read-only until payment is confirmed.

Order Export Workflow Step

Add a workflow step using the Magento connector to trigger exports:

{
  "Name": "ExportToMagento",
  "Connector": "Magento",
  "Active": true
}

Error Handling

• Order sync continues even if individual orders fail
• Product import logs missing parent products for variants

Troubleshooting

Common Issues

Debugging Tips

1. Check scheduled task logs for sync errors
2. Verify connector options are correctly configured
3. Test API connectivity with Magento admin
4. Check order events for export status
5. Verify market/store mappings for multi-store setups

API Endpoints Used