Let me be blunt: OMS–WMS integration breaks for almost every seller I know. Orders leave the OMS; the warehouse says they never arrived. The warehouse says they shipped; the buyer says nothing showed up. Both systems show green, and the seller eats the bad review, the refund, and the shipping cost.
I've sold cross-border for five years. The first three I ran my own small warehouse; when volume outgrew it, I moved to a 3PL in Los Angeles in September 2024. Same OMS, new WMS — and the first week taught me lessons I paid for in real money.
The first one was SKU mapping.
We had 800+ SKUs. Before go-live I exported the list so the 3PL could create product records in their WMS. Sounds simple. Week one: 100+ orders stuck "pending" — pushed fine, but the WMS couldn't find the SKU. They'd created about 700; the other 100+ were new products from the last two months, missing from my export. Orders sat for two days before I spotted them in the exception report, right as fall/winter SKUs were ramping. 100+ orders shipped two days late; customer service got yelled at all week.
Hard lesson: the SKU mapping table must reconcile at 100%, not 99%. I export every SKU from the OMS and vlookup it against WMS item codes — one missing row, no go-live. And a hard rule: no listing goes live until its SKU mapping exists in the WMS. Mapping first, listing second.
OMS WMS Integration Starts With the Field Mapping Table
An order push from OMS to WMS is, at its core, a field mapping table — and ninety percent of integration incidents live in it. Most guides on OMS WMS integration field mapping stop at the table. The table is the easy part; the exceptions are where sellers bleed money. Here's our current version, with the last column marking where I personally got burned:
| OMS field | WMS field | Where it breaks |
|---|---|---|
| Marketplace order number | External order reference | The two systems use different order numbers — send both; the WMS must dedupe on the external reference |
| OMS order number | Outbound order number | Don't use the marketplace order number here — one buyer placing two orders in a day will collide |
| SKU | Item code | Mapping table must exist first; "create mapping" is a mandatory step in every new-product launch |
| Quantity | Pick quantity | Units! Selling by the case vs. by the piece must resolve to a single unit in the WMS |
| Recipient / address / city / state / ZIP / phone | Ship-to info | Address line 2 (apt, unit, suite) must be sent — many integrations only send line 1 |
| Shipping method | Carrier + service code | Never send display names like "Standard" — send codes both sides agreed on beforehand |
| Buyer note | Packing note | Its own field — never stuff it into the address lines or address validation fails |
| Store / merchant | Merchant code | Mandatory when multiple stores share one WMS, or inventory gets deducted from the wrong owner |
The sneakiest is quantity units. Our variety pack sold by the case — 12 pieces each. The OMS sent "cases," the WMS record was in "pieces," and the first 20 orders picked 20 pieces instead of 20 cases. Buyers got one piece, assumed it was the whole case, and opened disputes everywhere. We added a "unit conversion" column and flagged every variety pack. Hasn't happened since.
Never send shipping method names, only codes. We started with "standard" and "expedited" — the 3PL uses five carriers, each with its own "standard," and the WMS couldn't tell which we meant. Now both sides share a code table, the OMS sends codes like GROUND_HOME, and arguments dropped ninety percent.
Four Exceptions in OMS WMS Integration You'll See Every Week
I keep this matrix pinned — symptom, auto handling, and when a human steps in. Four types cover nearly everything:
| Exception | Symptom | Auto handling | Human steps in when |
|---|---|---|---|
| Unmapped SKU | Order stuck pending in WMS | Held + added to exception report | Same day: add the mapping, manually re-push |
| Short inventory | Not enough stock to fulfill | Hold the whole order, or ship available qty per rule | Unresolved after 4 hours — CS contacts the buyer |
| Bad address | Validation fails / returned parcel | Held | Manually verify the address, fix it, re-push |
| Duplicate push | Same external ref arrives twice | WMS dedupes on the external ref and drops it | No action needed — but the drop count must show in the report |
Duplicate push deserves its own story — Black Friday 2024. Our push was real-time API; the network hiccuped, the OMS timed out and retried. With no dedupe on the external order number, the WMS created two outbound orders and the night shift shipped both. One buyer got two parcels and returned one — shipping plus product cost me nearly $40 on that order. About a dozen duplicates that night. Still stings.
Two hard rules came out of it. One: the WMS must dedupe on the marketplace order number — idempotency goes in the contract, not a handshake. Two: before go-live I test it myself, re-pushing the same order 10 times. One outbound order is a pass; two means the 3PL goes back and fixes it.
Bad addresses deserve a note too. US address line 2 — apt, unit, suite — gets dropped constantly because mappings only send line 1. A batch of our apartment orders shipped without unit numbers, failed delivery, and came back: seven days round trip, straight to one-star reviews. Now the OMS blocks the push unless all four are present — recipient, address lines (line 2 included), ZIP, phone.
The Counterintuitive Take: Fewer Fields, Fewer Problems
Most people think more fields means better integration and try to send everything down to coupon codes. I thought so too, until it bit me: every extra field is another failure point.
A WMS executes. It needs the recipient, the contents, the quantity, the ship method, and any packing note. Coupon info, ad source — the WMS can't use them, and one malformed field can fail the whole order. We cut our payload from 30+ fields to 18; the exception rate dropped by half.
Related trade-off: real-time push vs. scheduled batch. Real-time feels great — orders hit the warehouse in seconds — but one network blip means lost or duplicate orders, usually at 2 a.m. with nobody watching. Batch (a file every 15 minutes) looks dumb but is replayable and reconcilable; when it breaks you re-run the file. My setup: real-time push plus a reconciliation job every 15 minutes comparing order numbers across both systems. Orders in the OMS but missing from the WMS get auto re-pushed. Want both benefits? Do both jobs.
Go-Live Checklist: 7 Things to Verify the Night Before
Our second cutover ran on this list — seven checkmarks, or no go-live:
- Idempotency: deliberately re-push the same order 10 times — the WMS must create exactly 1 outbound order.
- Full SKU reconciliation: export every SKU from the OMS, vlookup against WMS item codes. One missing row = no go-live.
- Unit conversions: variety packs and case packs, every conversion spelled out in the mapping table.
- Address completeness: recipient, address lines (line 2 included), ZIP, phone — the OMS blocks the push if any is missing.
- Carrier code table: both sides agree on codes; no display names, no fuzzy words like "standard."
- Notes get their own field: buyer notes never go into address lines.
- 50-order sandbox run: use real historical orders, deliberately including dirty data — apartment numbers, PO boxes, remote ZIPs, missing phones.
Reading the Exception Report: Three Numbers
Every morning at 8, the exception report lands. Three numbers, nothing else:
First, pending order count. Single digits is normal; over 20 and I'm calling the 3PL.
Second, the pending-reason breakdown. If the same cause tops the list three days running, the mapping table or rule needs fixing — that's systemic, not random.
Third, orders pending over 24 hours — the red line. Pending is fine; ignored is not. Anything stuck that long is a late shipment in the making; clear it the same day.
First two weeks: exception rate (pending + mis-ships over total orders) sat around 8%. Two months on this routine: under 0.5%. Peak weeks like Black Friday bounce to ~1%, but it's all visible in the report and all actionable.
OMS–WMS integration isn't a technology problem. It's an attention problem. Get the OMS WMS integration field mapping right, give every exception an owner, and read the daily report — do those three and the failure rate drops by ninety percent. Tested it myself — from 8% to 0.5% on that table and that email.
By Ah K, E-commerce Seller (5 yrs)
