ERP-to-WMS & 3PL Integration Playbook

TL;DR

• Bottom line: ERP-to-WMS integration follows a standard lifecycle: order release (ERP→WMS) → allocation → pick/pack/ship → shipping confirmation (WMS→ERP) → inventory reconciliation. Use EDI 940/945 for traditional WMS, REST APIs for cloud-native WMS and 3PLs.
• Key limit: Inventory sync timing is the #1 failure point — real-time WMS updates with batch ERP reconciliation creates phantom variances that cascade into fulfillment errors.
• Watch out for: EDI 940 requires exact item master alignment between ERP and WMS — mismatched SKU mappings silently drop order lines.
• Best for: Organizations running dedicated WMS (Manhattan, Blue Yonder, Oracle WMS Cloud, SAP EWM) or outsourcing fulfillment to 3PLs (ShipBob, ShipStation, Flexport).
• Authentication: Manhattan/Oracle use OAuth 2.0; Blue Yonder uses MOCA sessions + API gateway tokens; 3PLs use API keys over HTTPS.

System Profile

This integration playbook covers the end-to-end data flow between ERP systems and warehouse management systems (WMS) or third-party logistics (3PL) providers. It addresses both enterprise WMS platforms (Manhattan Active WM, Blue Yonder, Oracle WMS Cloud, SAP EWM) and cloud-based 3PL APIs (ShipBob, ShipStation, Flexport). The playbook applies regardless of which ERP system is the source — SAP S/4HANA, Oracle ERP Cloud, NetSuite, Microsoft Dynamics 365, or others.

API Surfaces & Capabilities

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Authentication Gotchas

• Manhattan Active WM OAuth tokens are tenant-scoped — multiple warehouses on different tenants need separate credentials per tenant. [src1]
• Blue Yonder MOCA sessions are stateful and server-affinity is required — load balancers without sticky sessions cause silent data corruption. [src2]
• ShipBob API keys are channel-scoped — a single merchant with multiple sales channels needs separate keys and routing logic. [src6]

Constraints

• EDI 940/945 cannot be sent directly via HTTP POST — requires a certified EDI translator (SPS Commerce, TrueCommerce, Cleo) or VAN.
• Manhattan Active WM does not support EDI natively — EDI must be translated to REST API calls via middleware.
• SAP EWM embedded edition (within S/4HANA) does not require separate integration — it shares the same database. Only decentralized EWM needs IDoc/RFC.
• Oracle WMS Cloud REST API requires version prefix in every URI (e.g., /wms/api/v9/) — omitting the version returns 404.
• 3PL APIs do not support partial shipments natively — split shipments require multiple fulfillment orders with line-item allocation in middleware.
• Inventory quantity types differ across systems: WMS tracks on-hand, allocated, picked, damaged, quarantined; ERP typically only consumes available and on-hand.
• Blue Yonder MOCA is not HTTP-compatible — requires MOCA Java client, Integration Server, or middleware translation layer.

Integration Pattern Decision Tree

START — ERP-to-WMS/3PL Integration
|-- What WMS/3PL system?
|   |-- Manhattan Active WM -> REST API (OAuth 2.0)
|   |-- Blue Yonder WMS -> MOCA (legacy) or Integration API (modern)
|   |-- Oracle WMS Cloud -> REST API (XML/JSON)
|   |-- SAP EWM Embedded -> No external integration needed (shared DB)
|   |-- SAP EWM Decentralized -> IDoc (batch) or OData (real-time)
|   |-- 3PL (ShipBob/ShipStation/Flexport) -> REST API
|   +-- Legacy/custom WMS -> EDI 940/945 via VAN
|-- What's the integration pattern?
|   |-- Real-time order release (<1 min latency)
|   |   |-- < 500 orders/day -> Direct REST API calls, synchronous
|   |   |-- 500-5,000 orders/day -> Event-driven (middleware routes)
|   |   +-- > 5,000 orders/day -> Message queue + async workers
|   |-- Batch order release (scheduled waves)
|   |   |-- EDI 940 via VAN -> Hourly/daily batch files
|   |   |-- File-based (CSV/XML) -> SFTP drop folder
|   |   +-- IDoc batch (SAP EWM) -> Scheduled ALE distribution
|   +-- Hybrid (real-time order + batch inventory) -> Most common pattern
|-- Which data flows?
|   |-- ERP -> WMS: Sales order, PO receipt, transfer orders, item master
|   |-- WMS -> ERP: Ship confirm, ASN (856), inventory adjustments
|   +-- Bidirectional: Inventory levels (real-time WMS, periodic ERP recon)
+-- Error tolerance?
    |-- Zero-loss -> Idempotent APIs + DLQ + reconciliation job
    +-- Best-effort -> Retry with exponential backoff

Quick Reference — Order-to-Ship Process Flow

Step-by-Step Integration Guide

1. Establish connectivity and authenticate

Set up authenticated connections to both ERP and WMS systems. [src1, src3]

# Manhattan Active WM — OAuth 2.0 token request
curl -X POST https://{tenant}.manh.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=wm-api"

# ShipBob — API key authentication
curl -X GET https://api.shipbob.com/1.0/order \
  -H "Authorization: Bearer {SHIPBOB_API_KEY}" \
  -H "shipbob_channel_id: {CHANNEL_ID}"

Verify: Successful HTTP 200 response with valid JSON body.

2. Sync item master data (prerequisite)

Before any order flow, ensure item master (SKU) data is synchronized between ERP and WMS. [src7]

{
  "sku": "WIDGET-001",
  "description": "Blue Widget 10-pack",
  "upc": "012345678901",
  "weight": 2.5,
  "weight_uom": "LB",
  "dimensions": { "length": 12, "width": 8, "height": 6, "uom": "IN" },
  "lot_tracked": true,
  "serial_tracked": false,
  "hazmat": false,
  "storage_class": "AMBIENT",
  "erp_item_id": "MAT-100042"
}

Verify: Query WMS for the item by SKU — confirm all fields match ERP source.

3. Release orders from ERP to WMS

Push sales orders from ERP to WMS for fulfillment. [src1, src4]

// Manhattan Active WM REST order release
{
  "orderNumber": "SO-2026-00142",
  "orderType": "SALES",
  "priority": 2,
  "requestedShipDate": "2026-03-05",
  "shipTo": {
    "name": "Jane Smith",
    "address1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US"
  },
  "carrier": "FEDEX",
  "serviceLevel": "GROUND",
  "lines": [
    { "lineNumber": 1, "sku": "WIDGET-001", "quantity": 10, "uom": "EA" }
  ]
}

Verify: WMS returns HTTP 201 (REST) or functional acknowledgment 997 (EDI). Order appears in WMS work queue.

4. Receive shipping confirmation from WMS

After pick/pack/ship, WMS sends shipment details back to ERP. [src4, src5]

{
  "orderNumber": "SO-2026-00142",
  "shipmentId": "SHP-88901",
  "shippedDate": "2026-03-04T14:30:00Z",
  "carrier": "FedEx",
  "trackingNumber": "794644790132",
  "lines": [
    { "lineNumber": 1, "sku": "WIDGET-001", "shippedQuantity": 10, "lotNumber": "LOT-2026-A1" }
  ],
  "packages": [
    { "packageId": "PKG-001", "sscc18": "00100123456789012345", "trackingNumber": "794644790132" }
  ]
}

Verify: ERP shows shipment posted, inventory decremented, tracking stored on sales order.

5. Implement inventory reconciliation

Run nightly reconciliation between WMS and ERP to catch drift. [src7]

SELECT w.sku, w.location_id,
  w.on_hand_qty AS wms_qty, e.on_hand_qty AS erp_qty,
  (w.on_hand_qty - e.on_hand_qty) AS variance
FROM wms_inventory w
LEFT JOIN erp_inventory e ON w.sku = e.sku AND w.warehouse_id = e.warehouse_id
WHERE ABS(w.on_hand_qty - e.on_hand_qty) > 0
ORDER BY ABS(variance) DESC;

Verify: Variance report shows zero or known-exception rows only.

6. Configure ASN (EDI 856) for retail fulfillment

If shipping to retailers, generate ASN with SSCC-18 barcodes. Late or missing ASNs trigger chargebacks ($50-$500 per occurrence). [src4, src5]

; EDI 856 — Advance Ship Notice (simplified)
ST*856*0001~
BSN*00*SHP-88901*20260304*1430*0001~
HL*1**S~
TD5**2*FEDX*FG~
REF*CN*794644790132~
N1*ST*Jane Smith~
HL*2*1*O~
PRF*PO-2026-00142~
HL*3*2*P~
MAN*GM*00100123456789012345~
HL*4*3*I~
LIN*1*VN*WIDGET-001*UP*012345678901~
SN1*1*10*EA~
SE*14*0001~

Verify: Retailer EDI system returns 997 functional acknowledgment within SLA.

Code Examples

Python: Order release to ShipBob 3PL

# Input:  Sales order from ERP (order_number, items, ship_to)
# Output: ShipBob order ID and status

import requests  # requests==2.31.0

SHIPBOB_API_KEY = "your_api_key"
CHANNEL_ID = "your_channel_id"

headers = {
    "Authorization": f"Bearer {SHIPBOB_API_KEY}",
    "Content-Type": "application/json",
    "shipbob_channel_id": CHANNEL_ID
}

order_payload = {
    "reference_id": "SO-2026-00142",
    "order_number": "SO-2026-00142",
    "type": "DTC",
    "shipping_method": "Standard",
    "recipient": {
        "name": "Jane Smith",
        "address": {
            "address1": "123 Main St",
            "city": "Austin", "state": "TX",
            "zip_code": "78701", "country": "US"
        }
    },
    "products": [{"reference_id": "WIDGET-001", "quantity": 10}]
}

resp = requests.post("https://api.shipbob.com/1.0/order",
                     json=order_payload, headers=headers)
resp.raise_for_status()
print(f"ShipBob Order ID: {resp.json()['id']}")

JavaScript/Node.js: Poll ShipStation for shipment updates

// Input:  Date range for shipped orders
// Output: Array of shipment objects with tracking numbers

const axios = require('axios'); // [email protected]
const SHIPSTATION_KEY = 'your_api_key';
const SHIPSTATION_SECRET = 'your_api_secret';
const auth = Buffer.from(`${SHIPSTATION_KEY}:${SHIPSTATION_SECRET}`).toString('base64');

async function getShipments(shipDateStart, shipDateEnd) {
  const shipments = [];
  let page = 1, hasMore = true;
  while (hasMore) {
    const resp = await axios.get(
      `https://ssapi.shipstation.com/shipments?shipDateStart=${shipDateStart}&shipDateEnd=${shipDateEnd}&pageSize=500&page=${page}`,
      { headers: { Authorization: `Basic ${auth}` } }
    );
    shipments.push(...resp.data.shipments);
    hasMore = resp.data.pages > page;
    page++;
  }
  return shipments.map(s => ({
    orderNumber: s.orderNumber,
    trackingNumber: s.trackingNumber,
    carrier: s.carrierCode,
    shippedDate: s.shipDate
  }));
}

cURL: Query Manhattan Active WM inventory

# Step 1: Get access token
TOKEN=$(curl -s -X POST https://{tenant}.manh.com/oauth/token \
  -d "grant_type=client_credentials&client_id={ID}&client_secret={SECRET}" \
  | jq -r '.access_token')

# Step 2: Query inventory for specific SKU
curl -s "https://{tenant}.manh.com/api/wm/inventory?sku=WIDGET-001" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.inventory[]'

Data Mapping

Field Mapping Reference — ERP to WMS Order Release

Data Type Gotchas

• Date format inconsistency: ISO 8601 vs YYYYMMDD vs CCYYMMDD (EDI). Always normalize in middleware. [src4]
• Quantity decimals: WMS uses integers for pieces; ERP may send decimals for weight-based items. [src7]
• International addresses: EDI 940 limited to ASCII — middleware must transliterate UTF-8. [src4]
• SSCC-18 check digit (Mod 10) must be calculated by WMS/middleware — ERPs typically do not generate SSCC-18. [src5]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Item master drift: WMS and ERP item masters diverge — new items not synced to WMS. Fix: Automated item master sync before every order release wave. [src7]
• Partial shipment mismatch: WMS ships 8 of 10 units but ERP expects all-or-nothing. Fix: Configure ERP to accept partial shipments; create backorder lines. [src1]
• EDI 856 timing: Late ASN triggers retailer chargeback ($50-$500). Fix: Trigger 856 on carrier manifest close, not batch schedule. [src4]
• Inventory snapshot timing: WMS sends at 11:59 PM, ERP processes at 12:01 AM. Fix: Use event-driven inventory for ATP; batch recon for audit only. [src7]
• Carrier code mapping failure: ERP sends "FEDEX_GROUND" but WMS expects "FG". Fix: Maintain carrier crosswalk table in middleware. [src1]
• Webhook delivery failures (3PL): Endpoint downtime loses shipment notifications. Fix: Poll as fallback every 15 min; deduplicate by shipment ID. [src6]

Anti-Patterns

Wrong: Polling WMS for order status every minute

# BAD — polling creates load and still has up to 60s latency
while True:
    orders = wms_api.get_orders(status="shipped")
    for order in orders:
        erp.update_shipment(order)
    time.sleep(60)

Correct: Use webhooks or event-driven notifications

# GOOD — WMS pushes ship confirmations as they happen
@app.route('/webhook/wms/shipment', methods=['POST'])
def handle_shipment_webhook():
    payload = request.json
    if db.shipment_processed(payload['shipmentId']):
        return jsonify({"status": "duplicate"}), 200
    erp.post_goods_issue(payload)
    db.mark_shipment_processed(payload['shipmentId'])
    return jsonify({"status": "ok"}), 200

Wrong: Sending orders without validating item master

// BAD — orders with unknown SKUs silently fail
async function releaseOrder(order) {
  await wmsApi.post('/orders', order);
}

Correct: Pre-validate all SKUs against WMS item master

// GOOD — catch missing items before fulfillment delays
async function releaseOrder(order) {
  const wmsCatalog = await wmsApi.get('/items?skus=' + order.lines.map(l => l.sku).join(','));
  const wmsSkus = new Set(wmsCatalog.data.map(i => i.sku));
  const missing = order.lines.filter(l => !wmsSkus.has(l.sku));
  if (missing.length > 0) {
    await syncItemMaster(missing.map(l => l.sku));
  }
  await wmsApi.post('/orders', order);
}

Wrong: Using real-time inventory sync as single source of truth

# BAD — eventual consistency gaps cause silent inventory drift
def get_available_inventory(sku):
    return wms_api.get_inventory(sku)['available']

Correct: Real-time for operations, nightly reconciliation for accuracy

# GOOD — use WMS for real-time ATP, reconcile nightly
def reconcile_inventory():
    wms_snapshot = wms_api.get_full_inventory_snapshot()
    erp_snapshot = erp_api.get_inventory_by_warehouse()
    variances = find_variances(wms_snapshot, erp_snapshot)
    if variances:
        create_cycle_count_request(variances)

Common Pitfalls

• Master data sync order matters: Loading orders before items causes mass failures. Fix: Sync in order: warehouses, items, addresses, then orders. [src7]
• UOM conversion failures: ERP sends cases (CS), WMS operates in eaches (EA). Fix: Maintain UOM conversion table in middleware with mandatory validation. [src1]
• Timezone mismatches in SLA calculation: ERP uses UTC, WMS uses local time, retailer expects EST. Fix: Normalize all dates to UTC in transit; convert to local at display. [src7]
• Over-relying on EDI batch schedules: Hourly 940 batch means up to 59 min wait. Fix: Micro-batch on order event or switch to real-time API. [src4]
• Ignoring WMS capacity constraints: Releasing 10,000 orders at once overwhelms wave planning. Fix: Throttled release at warehouse pick rate (e.g., 500/hour). [src1]
• Not testing with realistic volumes: Works with 10 orders in QA, collapses at 5,000 in production. Fix: Load-test with 2x expected peak volume before go-live. [src7]

Diagnostic Commands

# Check ShipBob API connectivity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "shipbob_channel_id: {CHANNEL_ID}" \
  https://api.shipbob.com/1.0/product?limit=1

# Check ShipStation API connectivity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Basic {BASE64_KEY_SECRET}" \
  https://ssapi.shipstation.com/orders?pageSize=1

# Test Manhattan Active WM OAuth token
curl -s -X POST https://{tenant}.manh.com/oauth/token \
  -d "grant_type=client_credentials&client_id={ID}&client_secret={SECRET}" \
  | jq '{token: .access_token[:20], expires: .expires_in}'

# SAP EWM — check IDoc status
# Transaction WE02: filter by message type WMMBXY
# Transaction SM58: check tRFC/qRFC queue for stuck IDocs

# EDI 940 transmission verification
# SPS Commerce portal -> Transactions -> filter Document Type 940
# Check 997 status: Accepted (A) vs Rejected (R)

Version History & Compatibility

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• WMS API capabilities and rate limits vary by edition and licensing tier — values in this card represent enterprise/standard editions.
• EDI 940/945/856 implementations vary by trading partner — each retailer has its own implementation guide beyond the X12 standard.
• 3PL API capabilities are evolving rapidly — always check the developer portal for the latest endpoints.
• SAP EWM embedded vs. decentralized architecture fundamentally changes the integration pattern.
• Carrier code mappings and UOM conversion tables are organization-specific — budget 20-30% of integration effort for mapping table creation.
• This card covers technical integration patterns. Warehouse operational design (slotting, wave planning, labor management) is outside scope.