Integrations Hub — Operational Control Through System Connectivity

Order

Owner: The eCommerce platform or OMS is the authoritative source until the order is released to the warehouse. State transitions: Received → Validated → Accepted → Picking → Picked → Packed → Dispatched → In Transit → Delivered. What happens when critical fields are missing: If an order arrives without a valid delivery address, contact phone, or required special handling notes, it goes into an exception queue until the missing data arrives or is manually provided. The warehouse doesn't ship "best guess" addresses.

SKU/Catalog

Owner: The ERP or product management system owns the master, but the warehouse system needs a synchronized copy. State transitions: Product defined → Variants assigned → Pack configuration locked → Barcode assigned → Ready for receiving. What happens when codes change: If a supplier changes a SKU code or barcode, the integration captures the equivalence (old code = new code). Both codes remain recognizable for a transition period so existing inbound doesn't break. After the transition window, the old code is retired.

Inventory

Owner: The warehouse WMS or inventory system is the source of truth for physical reality. The eCommerce system and ERP read from the warehouse system, not the other way around. State transitions: On-hand (physical count) → Available (on-hand minus allocated) → Allocated (reserved for a specific order) → In-pick (physically being picked) → Shipped (gone). What happens when count is wrong: When the warehouse count doesn't match what the eCommerce system thinks is available, a reconciliation flag is raised. The reconciliation is manual: a physical count wins, the system is corrected, and the variance is traced. Until reconciliation, the warehouse count is published as available (conservative approach).

Shipment

Owner: The warehouse operates the shipment until the carrier accepts it. The carrier owns it in transit. The destination confirms receipt. State transitions: Staged (goods are ready) → Handed to carrier (proof of receipt) → In transit (carrier responsibility) → Delivered (destination confirms). What happens when proof never arrives: If a shipment is marked as "handed to carrier" but the carrier never acknowledges receipt or a tracking number is not issued within 24 hours, an alert is triggered and the shipment is manually reviewed. It's possible the goods are still at the warehouse; the system record is ahead of reality.

Return

Owner: The returns authorization system is the source of truth until the return is triaged; after triage, the warehouse execution system owns the disposition. State transitions: Initiated (customer requests return) → Authorized (return is approved) → Shipped back → Received at warehouse → Triaged (grade assigned) → Restocked/Reworked/Disposed. What happens when triage is incomplete: If a return arrives without a clear triage decision, it stays in a quarantine hold until a decision comes from the Returns system or a manager manually assigns a grade. Nothing restocks until triage is complete.

Order Status Transitions

• Received → Accepted: Triggers on stock validation complete. Action: inventory is allocated; order is released to pick queue.
• Picking → Picked: Triggers on final pick confirmation (last line picked). Action: goods are physically moved to pack station; picker accountability closes.
• Packed → Dispatched: Triggers on carrier confirmation of pickup. Action: order is marked shipped in eCommerce system; customer receives tracking number.
• Dispatched → Delivered: Triggers on carrier delivery confirmation. Action: customer is notified; fulfillment closes. Control point: If an order is in "Picking" state but no pick activity occurs for 4 hours, an alert is raised. A stuck order indicates either a system failure (the order isn't in the pick system) or a operational failure (the order wasn't actually released to pick).

Inventory Status Transitions

• On-hand → Available: Triggered by cycle count or reconciliation confirmation. Action: the count is published to eCommerce system.
• Available → Allocated: Triggered by order acceptance. Action: quantity is reserved; eCommerce inventory is decremented.
• Allocated → In-pick: Triggered by pick line start. Action: warehouse acknowledges the allocation and begins execution.
• In-pick → Shipped: Triggered by carrier hand-off. Action: inventory movement is final; no edits are possible. Control point: If inventory shows 100 units available but a stock audit finds 80, the warehouse count (80) is published as true. The 20-unit variance is logged and investigated (damage, theft, miscounts, system error). eCommerce inventory is corrected immediately.

Shipment Status Transitions

• Staged → Handed to carrier: Requires carrier receipt confirmation. Action: tracking number is issued; warehouse closes responsibility.
• Handed to carrier → In transit: Carrier confirms pickup and provides tracking. Action: customer is notified with tracking number; fulfillment status is updated.
• In transit → Delivered: Carrier confirms delivery at destination address. Action: fulfillment is marked complete; customer receives delivery confirmation. Control point: If a shipment is marked "handed to carrier" but no carrier confirms receipt within 24 hours, the warehouse retrieves the goods and investigates. The shipment may still be physically at the dock; the system record is fiction.

SKU Code Changes

When a supplier changes a SKU code: - Equivalence is documented: old-sku-123 = new-sku-456. - Both codes are active during a transition window (typically 30 days). - Inbound is received under both codes and routed to the same physical inventory. - Pick algorithms prefer the new code but accept the old code. - After the transition window, the old code is retired.

Barcode / EAN Changes

When a supplier changes a product's barcode or EAN: - The integration maps: barcode-old = barcode-new. - The pick system accepts both codes and routes to the same physical unit. - Any system receiving a barcode scan validates it against both the active and legacy mapping. - After the transition window, legacy barcodes generate a warning, not a failure.

Bundle / Kit Logic

When multiple SKUs are combined into a single sellable unit (a bundle): - The bundle is defined as a separate entity with its own SKU in the eCommerce system. - The warehouse system tracks the bundle as a "kit" with component-level allocation rules. - Inventory for the bundle is calculated as: MIN(stock of component A, stock of component B, ...). - When a bundle order is picked, components are allocated from their respective inventory locations, not from a phantom "bundle inventory."** This prevents bundle logic from contaminating component inventory counts or creating phantom allocations.

Mandatory Fields and Minimum Identifiers

For any order to pick cleanly, these fields must be present and valid: - Order ID: unique, immutable identifier. - SKU: maps to a valid master catalog entry. - Quantity: positive integer matching the sellable unit definition. - Delivery address: complete street address, ZIP, country. - Contact phone: valid number for delivery coordination. - Special handling: any lane, delivery window, or packing requirement. If any of these fields are missing or ambiguous, the order is held until the data is provided or a manager makes an explicit decision.

API and Webhooks

For real-time or near-real-time synchronization: - eCommerce → Warehouse: Orders are pushed via API or webhook as they're placed or validated. The warehouse system acknowledges receipt and stores the order in a picking queue. - Warehouse → eCommerce: Shipment status (packed, dispatched, delivered) is pushed back via API. Inventory levels are published on a defined schedule (typically every 15–60 minutes) to keep availability accurate. - Inventory → ERP: Physical counts and reconciliation results are published so the ERP's inventory matches warehouse reality. Contracts: API endpoints must be versioned; webhook payloads must include a timestamp and a unique event ID (to detect duplicates); failed deliveries must be retried with exponential backoff; and critical data (order ID, SKU, quantity) must be validated on receipt.

Structured Files (CSV / Templates)

For scheduled, batch synchronization: - Purchase orders arrive as a CSV file with columns: order-id, sku, quantity, delivery-date, special-notes. - Inventory snapshots are exported as a CSV file daily: sku, on-hand, allocated, available. - Returns data is sent as a CSV with columns: return-id, original-order-id, reason, disposition. Contracts: Files are delivered to a defined SFTP location on a schedule; file naming includes a timestamp; headers are validated before processing; and failed records are logged separately for manual review.

Email-Based Handoffs

For constrained B2B / retail workflows where API isn't available: - Routing guides and labeling specs arrive as an email attachment (PDF or CSV). The warehouse team reviews, confirms understanding, and loads the spec into the operation. - Purchase orders arrive as structured email text or attachment, typically from a retail buyer's ERP. - Shipment confirmations are sent back to the buyer as an email with packing list, carton counts, and expected delivery time. Contracts: Email is dated and versioned (routing guide v2 replaces v1, with a cutover date); responses are logged; and version control is maintained manually but rigorously.

eCommerce Platforms

Shopify: Orders are synced via the Shopify API; inventory is published via a Shopify app that reads from the warehouse WMS; fulfillment status is updated through the Shopify fulfillment API so customers see real tracking. WooCommerce: Orders are pulled via the WooCommerce REST API on a defined interval (typically every 5–15 minutes); inventory is synchronized using a custom integration or a third-party plugin (like TrackStock); fulfillment updates are pushed back to WooCommerce via the API. PrestaShop: Orders are fetched via the PrestaShop Web Service API; inventory levels are synchronized on a schedule; order status updates are pushed back to trigger customer notifications. Magento: Orders are synced via the Magento REST API; inventory is managed through a WMS-to-Magento integration; fulfillment events are published back to trigger shipment notifications.

Marketplaces

Amazon: Order data is pulled via the Amazon Seller Central API (Selling Partner API). Inventory is fed from the warehouse WMS to Amazon MWS (Marketplace Web Service) to prevent overselling. Shipments are closed through the SP-API by uploading carrier tracking numbers. Returns flow back via Amazon's returns API and are triaged in the warehouse. Mirakl: Orders are received via Mirakl's API and consolidated with direct orders. Inventory is published to Mirakl's platform so all sellers have accurate stock. Shipment and return data flow bidirectionally through the Mirakl platform API. eBay: Orders are synced via the eBay Trading API or REST API; inventory is managed to prevent double-selling; shipment confirmation and tracking are uploaded to trigger buyer notifications. Etsy: Orders are pulled via the Etsy API v3; order-level notes and customizations are captured; fulfillment status is updated back to Etsy so customers see delivery progress.

ERP/OMS Systems

Odoo: The Odoo database is the ERP; inventory is stored in the Odoo module, but the warehouse WMS is the physical source of truth. Bidirectional sync is maintained: Odoo creates purchase orders that flow to the warehouse; the warehouse inventory positions flow back to Odoo so financial reporting is accurate. SAP Business One (B1): B1 is often the master for product master data and customer orders; the warehouse system receives orders from B1 and returns inventory positions back so B1's available-to-promise (ATP) is accurate. Microsoft Dynamics 365: D365 handles financials and customer data; orders are created in D365 and flow to the warehouse; fulfillment data is returned to D365 so revenue is recognized accurately. NetSuite: NetSuite is the master ERP; orders are created in NetSuite, fulfillment data returns from the warehouse, and NetSuite's inventory is updated for accounting purposes.

Shipping Layer

Shipping integrations are kept intentionally tool-agnostic. We support: - Label generation: Carrier APIs (DHL, UPS, DPD, Correos) are used to generate labels based on shipment weight and destination. - Service selection: Based on delivery requirements (next-day, ground, economy), the system selects the appropriate carrier service. - Tracking events: Carrier webhooks push tracking updates back to the warehouse system so shipment status stays current. - Shipment closure: Once a carrier provides proof of pickup and a tracking number, the shipment is marked as dispatched.

Duplicate Protection

When a webhook is retried or a batch file is processed twice, duplicates can be created. We prevent this through: - Idempotent keys: Each order or shipment event includes a unique key (order-id + timestamp, or uuid). The warehouse system checks: has this key already been processed? If yes, the duplicate is logged and discarded. - Database constraints: Orders with the same ID cannot be inserted twice. If a duplicate arrives, the database rejects it, an alert is raised, and the duplicate is logged.

Exception Queues

When data is invalid or missing, it doesn't disappear. It goes to an exception queue where it waits for clarification or manual intervention: - Invalid orders (missing address, invalid SKU) are held in an "On Hold" queue. - Inventory mismatches (system says 100 but warehouse counts 80) are logged and reconciliation is triggered. - Incomplete shipments (packed but no carrier assigned) are flagged and held until closure is complete. A manager reviews exceptions daily, decides what to do (correct the data, cancel the order, escalate), and documents the decision. Exceptions don't auto-resolve.

Acceptance Tests

Before an integration goes live, we run acceptance tests: - Order flow: A test order is placed in the eCommerce system. We verify it arrives in the warehouse WMS, can be picked and packed, and successfully syncs back as shipped with tracking. - Inventory sync: We change inventory in the warehouse system and verify the eCommerce platform reflects the change within the expected sync window. - Variant handling: We test a variant order (e.g., size M, color blue) to ensure the right component is picked. - Bundle/kit order: A bundled order is placed and we verify the correct components are allocated and picked. - Partial order: We intentionally short an order, cancel a line, and verify the system handles the partial correctly. - Return flow: A completed order is returned; we verify it arrives in the returns system, is triaged, and is restocked correctly.

Manual Fallback Controls

When systems are down or data is unreliable, there's always a manual fallback: - Orders arriving via email: If the eCommerce API is down, orders can arrive via email. The warehouse team processes them manually into the picking system, with a flag marking them as manual entry. - Inventory via spreadsheet: If the WMS is down, inventory can be updated via a CSV file and manually imported. - Shipment tracking via email: If the carrier API is unavailable, tracking numbers can be entered manually into the system. Manual fallbacks are slower and riskier, but they preserve operational continuity. They're logged as exceptions and reviewed after the system is restored.

Monitoring Signals

We track integration health through: - Order lag: How long between order placement and arrival in the warehouse system? If the average lag is 15 minutes but it suddenly jumps to 2 hours, that's a signal something is wrong. - Inventory divergence: Does the warehouse count match the published count? If they diverge beyond a threshold (e.g., ±5%), an alert is raised. - Failed webhooks: Are webhooks being rejected or timing out? Each failure is logged and if the failure rate exceeds a threshold, the integration is manually reviewed. - Exception queue depth: How many orders are on hold? A growing queue indicates a problem (bad data, system failure). These signals drive proactive investigation before customers see problems.

1. Technology Stack

• Which eCommerce platforms are you using? (Shopify, WooCommerce, custom?)
• Which ERP or OMS? (Odoo, SAP B1, custom?)
• Do you have an existing WMS or inventory system?
• Which carriers do you use? (DHL, UPS, DPD, Correos, other?)

2. SKU and Catalog Structure

• How are SKUs identified? (Internal code, GTIN, supplier code?)
• Do you have variants? (Size, color, weight?) How are they represented?
• Do you sell bundles or kits? How are they managed?
• Are there SKU changes planned (migrations, supplier changes)?

3. Order Rules

• When is an order "valid to pick"? (At payment, at address validation, at stock check?)
• Can orders be edited after they're released to pick?
• How do you handle partial orders, cancellations, and substitutions?
• Are there channel-specific rules? (D2C vs. B2B, different carriers or delivery windows?)

4. Inventory Rules

• Where does inventory truth live (eCommerce system, ERP, WMS)?
• How is inventory allocated? (By order, by channel, by location?)
• What does "available" mean? (Raw count, minus allocated, minus reserved?)
• How often do you reconcile inventory?

5. Shipment Rules

• When does a shipment close? (When the warehouse hands it to the carrier, when the carrier confirms pickup, when it's delivered?)
• What proof is required? (Carrier receipt, tracking number, both?)
• How are returns initiated? (Customer portal, email, reverse label?)
• Are there channel-specific delivery windows or requirements?

6. Mandatory Fields

• What fields must be present on every order? (Address, phone, delivery notes, special handling?)
• Are there country-specific requirements? (VAT ID, customs info?)
• What's the minimum address detail required? (Street, ZIP, city, country?)

Role-Based Access

• Operations staff: Can view orders, inventory, and shipment status. Cannot force state changes.
• Warehouse managers: Can override exceptions, force inventory corrections, and manually close shipments.
• System administrators: Can create new integrations, change field mappings, and manage API credentials.
• Finance/reporting: Can view inventory and order data for reporting, but have no edit access.

Auditability

Every critical action is logged: - SKU master changes: Who changed what, when, and why (routing guide update, supplier migration, etc.). - Inventory corrections: Physical count, variance, who approved the correction, why. - Forced state changes: Order manually marked as shipped, return manually triaged, etc. Logged with the manager's name and reason.

Access Control

• API credentials are rotated regularly and never stored in code or email.
• Passwords are complex and not shared; API keys are used for system-to-system communication.
• IP whitelisting is used when available to restrict access to known networks.
• Sensitive data (customer addresses, phone numbers) is encrypted and access is logged.