Erp Integration

ERP Integration

Overview

Build integrations between e-commerce platforms and ERP systems (SAP, NetSuite, Odoo, Microsoft Dynamics) for bidirectional sync of orders, inventory, customers, and products. This skill covers integration architecture patterns (event-driven, polling, middleware), data mapping, conflict resolution, error handling with retry strategies, and idempotent sync that prevents duplicate records.

When to Use This Skill

• When connecting a storefront to an ERP for automated order fulfillment
• When syncing real-time inventory levels from an ERP/WMS to the e-commerce catalog
• When building customer master data sync between the storefront and ERP
• When implementing product and pricing feeds from the ERP to the storefront
• When designing a middleware layer to handle multiple integration points

Core Instructions

Step 1: Determine your platform and integration approach

Step 2: Platform-specific ERP integration

---

Shopify

Use a pre-built connector for standard ERPs:

1. For NetSuite: Install the official NetSuite Connector for Shopify from the Shopify App Store ($150-$300/month). It syncs orders, inventory, and customers bidirectionally with no custom code 2. For SAP: Use Celigo's SAP + Shopify integration template or contact your SAP partner for their Shopify connector 3. For Odoo: Install the Odoo Shopify Connector module in Odoo (free, community edition) — configure your Shopify API credentials in Odoo's settings

For custom ERP connections using Shopify webhooks:

1. In your Shopify admin, go to Settings → Notifications → Webhooks 2. Click Create webhook and add endpoints for orders/create, orders/paid, and inventory_levels/update 3. Your ERP middleware endpoint receives order data in JSON and transforms it to the ERP's format 4. For inventory sync back to Shopify, use the Inventory API to update levels after each ERP poll

---

WooCommerce

Use Zapier for simple, low-volume ERP sync:

1. Connect WooCommerce and your ERP (NetSuite, Odoo, Sage) in zapier.com 2. Create a Zap: trigger = New Order in WooCommerce, action = Create Sales Order in NetSuite 3. Map the WooCommerce order fields to your ERP's required fields in Zapier's field mapper 4. Zapier polls WooCommerce every 15 minutes on the free plan; upgrade to Starter ($19.99/month) for faster polling

For higher volume or custom ERP connections:

1. Install WP Webhooks (free, wordpress.org) to send WooCommerce events to your middleware 2. Use the WooCommerce REST API (/wp-json/wc/v3/orders) with OAuth 1.0a for your middleware to pull orders 3. For inventory sync from ERP to WooCommerce, use the WooCommerce Products API (PUT /wp-json/wc/v3/products/{id}) to update stock_quantity

---

Custom / Headless

Integration architecture — choose the pattern that fits your ERP:

Event-Driven (recommended for real-time order sync):
  Storefront → Webhook/Event → Message Queue (SQS/BullMQ) → ERP Adapter

Polling (for ERPs without webhooks, like legacy SAP installations):
  Scheduler → Poll ERP API → Transform → Update Storefront

Middleware Platform (for complex multi-system environments):
  Storefront ↔ Celigo / MuleSoft / Workato ↔ ERP

Idempotent order sync service:

// lib/erp/order-sync.ts
export async function syncOrder(orderId: string): Promise<void> {
  const order = await db.orders.getWithItems(orderId);

  // Check if already synced
  const existingSync = await db.syncLog.findByOrderId(orderId);
  if (existingSync?.status === 'synced') return;

  // Check ERP for existing record (guards against retries after partial failure)
  const existing = await erpAdapter.findOrderByExternalReference(order.orderNumber);
  if (existing) {
    await db.syncLog.upsert({ orderId, externalId: existing.erpOrderId, status: 'synced' });
    return;
  }

  try {
    const erpOrder = mapOrderToERP(order);
    const { erpOrderId } = await erpAdapter.createSalesOrder(erpOrder);
    await db.syncLog.upsert({ orderId, externalId: erpOrderId, status: 'synced', syncedAt: new Date() });
    await db.orders.updateMetadata(orderId, { erpOrderId });
  } catch (error) {
    await db.syncLog.upsert({ orderId, status: 'failed', lastError: error.message });
    throw error; // Let the retry mechanism handle it
  }
}

function mapOrderToERP(order: Order): ERPSalesOrder {
  return {
    externalReference: order.orderNumber,
    orderDate: order.createdAt.toISOString().split('T')[0],
    customer: {
      externalId: order.customer?.erpCustomerId || null,
      email: order.email,
      name: `${order.shippingAddress.firstName} ${order.shippingAddress.lastName}`,
    },
    shippingAddress: {
      line1: order.shippingAddress.street1,
      city: order.shippingAddress.city,
      state: order.shippingAddress.state,
      postalCode: order.shippingAddress.postalCode,
      country: order.shippingAddress.country,
    },
    lineItems: order.lineItems.map(item => ({
      sku: item.sku,
      quantity: item.quantity,
      unitPrice: item.unitPrice / 100,   // Convert cents to dollars for ERP
      taxAmount: item.taxAmount / 100,
    })),
    orderTotal: order.totalPrice / 100,
    currency: order.currency,
  };
}

BullMQ queue for reliable order sync with exponential backoff retries:

import { Queue, Worker, QueueEvents } from 'bullmq';

const orderSyncQueue = new Queue('order-sync', {
  connection: { host: process.env.REDIS_HOST, port: 6379 },
  defaultJobOptions: {
    attempts: 5,
    backoff: { type: 'exponential', delay: 5000 }, // 5s, 10s, 20s, 40s, 80s
    removeOnComplete: { count: 1000 },
    removeOnFail: { count: 5000 },
  },
});

// Producer: enqueue when order is placed
export async function onOrderPlaced(orderId: string) {
  await orderSyncQueue.add('sync-order', { orderId }, {
    jobId: `order-sync-${orderId}`, // Prevents duplicate queue entries
  });
}

// Consumer: process sync
new Worker('order-sync', async (job) => {
  await syncOrder(job.data.orderId);
}, { connection: { host: process.env.REDIS_HOST, port: 6379 }, concurrency: 5 });

Inventory sync (polling-based, ERP to storefront):

// lib/erp/inventory-sync.ts — run via scheduled job every 5 minutes
export async function syncInventoryLevels(): Promise<void> {
  const lastSyncAt = await redis.get('erp:inventory:last_sync');
  let page = 1, hasMore = true;

  while (hasMore) {
    const { items, hasMore: more } = await erpAdapter.getInventoryLevels({
      page, pageSize: 500,
      modifiedSince: lastSyncAt ? new Date(lastSyncAt) : undefined,
    });

    for (const item of items) {
      // Available = On Hand - Reserved - Safety Stock
      const available = Math.max(0, item.onHandQuantity - item.reservedQuantity - (item.safetyStock || 0));
      const current = await db.inventory.getQuantityBySku(item.sku);
      if (current === available) continue; // Skip unchanged

      await db.inventory.updateBySku(item.sku, { quantity: available, lastSyncedAt: new Date() });
      // Update Redis cache for real-time product page availability
      const productId = await db.inventory.getProductIdBySku(item.sku);
      if (productId) await redis.setex(`inventory:${productId}`, 3600, String(available));
    }

    hasMore = more;
    page++;
  }

  await redis.set('erp:inventory:last_sync', new Date().toISOString());
}

Best Practices

• Make every sync operation idempotent — use external references (order number, SKU) to check for existing ERP records before creating; this prevents duplicates from retries
• Use a message queue for order sync — never call the ERP synchronously during checkout; enqueue and process asynchronously with retries
• Implement a dead-letter queue — after all retries are exhausted, move failed jobs to a DLQ for manual inspection; never silently drop messages
• Use delta sync, not full sync — query the ERP for records modified since the last sync timestamp; full syncs don't scale past a few thousand records
• Store the ERP record ID on your local records — after syncing an order, save the ERP order ID on your record for cross-referencing and future status lookups
• Calculate available inventory correctly — available = onHand - reserved - safetyStock and clamp to zero; never use raw on-hand quantity from the ERP

Common Pitfalls

Related Skills

• @webhook-architecture
• @marketplace-connectors
• @monitoring-alerting-commerce
• @product-information-management

Reliable Order Sync to ERP

Problem/Feature Description

GardenHarvest, a mid-size online retailer of gardening supplies, recently rolled out a new headless e-commerce storefront and connected it to their existing NetSuite ERP. Their engineering team quickly ran into a painful problem: whenever the ERP was slow or briefly unavailable during peak checkout hours, orders failed to sync, leaving operations staff scrambling to manually re-enter orders into NetSuite and customers without fulfillment updates.

The team has decided to decouple order syncing from the checkout flow entirely. They want a robust background processing system that picks up newly placed orders, attempts to push them to the ERP, and gracefully handles failures with automatic retries. They also need visibility into orders that could not be synced after all retry attempts — these must be preserved and accessible for manual intervention by the ops team, rather than simply being lost.

Output Specification

Implement the order sync background processing system in TypeScript. Produce the following files:

• src/queues/orderSyncQueue.ts — Queue setup, job producer function (called when an order is placed), and worker configuration
• src/services/orderSyncService.ts — The sync service logic: fetches the order, checks for prior sync, calls the ERP adapter, updates the sync log, and stores the ERP reference on the order
• src/queues/deadLetterQueue.ts — Dead letter queue setup, handler for moving exhausted jobs there, and alert logic
• src/routes/adminIntegrations.ts — Admin API endpoint(s) for managing stuck jobs from the dead letter queue

Include a src/types.ts with relevant TypeScript interfaces (OrderSyncPayload, RetryPolicy, SyncLogEntry, etc.).

Write a brief DESIGN.md explaining the architecture decisions made, including how retries work and how the dead letter queue fits in.

SAP S/4HANA Adapter and Order Mapping Layer

Problem/Feature Description

NordLight, a Scandinavian outdoor lighting brand, is migrating from a legacy monolith to a headless commerce platform. Their ERP of record is SAP S/4HANA, which the operations, finance, and logistics teams rely on for all order fulfillment and reporting. The new integration must push orders from the storefront into SAP as sales orders, but the engineering team has learned through painful experience that SAP's API has specific quirks — authentication requirements, strict field formats, and rate limits — that tripped up their first integration attempt.

The team wants to build a clean integration layer: a SAP-specific adapter that hides all SAP API details from the rest of the application, a data transformation layer that converts the e-commerce order format into SAP's expected format, and clear handling of pricing so that SAP's base prices and the storefront's promotional discounts don't interfere with each other. The adapter should also be designed for the long term — the team may need to add a NetSuite adapter next quarter, so the interface should be generic enough to support multiple ERP backends.

Output Specification

Implement the ERP adapter layer in TypeScript. Produce the following files:

• src/adapters/ERPAdapter.ts — The abstract ERPAdapter interface defining all methods
• src/adapters/SAPAdapter.ts — The SAP S/4HANA implementation of ERPAdapter
• src/mappers/orderMapper.ts — The transformation functions that convert e-commerce order objects to ERP-generic format (and SAP-specific format where needed)
• src/types.ts — Shared TypeScript types: ERPSalesOrder, ERPCustomer, ERPInventoryItem, ERPProduct, SAPConfig, etc.

Write a DESIGN.md that explains:

• How the adapter pattern keeps SAP-specific code isolated
• How pricing is handled to avoid overwriting promotional prices with ERP base prices
• How the SAP adapter handles API authentication requirements

Real-Time Inventory Availability Sync

Problem/Feature Description

BrightFrame, an online furniture retailer, sources most of its product catalog from a NetSuite ERP that manages warehouse stock across three fulfillment centers. Their storefront currently shows stale inventory — updated once per night via a full data dump — causing customers to add out-of-stock items to their cart and leading to a high rate of order cancellations. Customer complaints have spiked around popular product lines, and the merchandising team is losing trust in the website's stock indicators.

The engineering team needs a scheduled inventory sync service that runs frequently and keeps e-commerce stock levels closely aligned with ERP data. The service must be efficient enough to run often without hammering the ERP's API — meaning it should only pull records that have actually changed since the last run, handle large catalogs gracefully, and be fast to query at storefront request time.

Output Specification

Implement the inventory sync service in TypeScript. Produce the following files:

• src/services/inventorySyncService.ts — The core sync service with a syncInventoryLevels() method that performs the full sync cycle, including paginated ERP fetching, quantity calculation, database updates, and cache updates
• src/scheduler.ts — Scheduler setup that calls syncInventoryLevels() on a recurring basis
• src/types.ts — TypeScript interfaces for ERP inventory items, sync results, and related types

Write a short DESIGN.md explaining how the service avoids redundant updates, how it handles large catalogs, and how it keeps the storefront cache fresh.