Return Order Sync in Practice: One Strategy from WMS to Kingdee
What This Strategy Solves (Scenario and Value)
In return workflows, stores or e-commerce channels record sales return orders in the WMS front end, while finance and inventory need to post them and deduct stock in the ERP. If both systems are entered manually, it is very common to end up with matched document numbers but mismatched amounts, or a header that synced but line items that did not. We use the Qeasy data integration platform to host a single strategy that pushes return orders from the WMS to the ERP as-is, with reliable, gap-free incremental delivery.
Data Flow and Field Mapping (Source → Middle Layer → Target)
Data flow: WMS (source) → Qeasy middle layer → ERP (target). The middle layer handles status checks, code translation, and field enrichment.
Key field mapping:
| Business meaning | WMS source field (example) | Qeasy middle layer | ERP target field (example) |
|---|---|---|---|
| Document number | return_no | return_no | FBillNo |
| Return date | return_time | return_time (formatted) | FDate |
| Customer code | customer_code | customer_code | FCustomerID |
| Warehouse code | warehouse_code | warehouse_code | FStockID |
| SKU code | sku_code | sku_code | FMaterialID |
| Quantity | qty | qty | FQty |
| Unit price | price | price | FPrice |
| Refund amount | refund_amount | refund_amount | FAmount |
| Remark | remark | remark | FNote |
One engineering detail: warehouse, customer, and SKU codes follow different naming rules across the three systems. They must be normalized through a mapping table in the middle layer rather than hard-coded into scripts.
How to Configure on Qeasy
Configuring this strategy on Qeasy involves five core steps:
- Register data sources: connect the WMS as source and the ERP as target. Credentials go into the credential vault and never appear as plaintext inside the strategy.
- Set event triggers: returns are low-frequency with medium latency tolerance, so we recommend a combined trigger of "time-window polling + status change" rather than pure scheduled execution.
- Field mapping canvas: drag the mapping table into the canvas, keep two decimal places for numeric fields, and normalize dates to yyyy-MM-dd HH:mm:ss.
- Centralized code mapping: maintain warehouse, customer, and SKU codes in Qeasy's master-data mapping module so any rule change happens in one place.
- Error handling: enable staged error isolation—header failures do not block header retries, line failures enter a separate queue—so one bad return does not stall the entire batch.
Implementation Steps (Phased Scheduling)
When we helped a retail enterprise go live on-site, we ran the rollout in three phases:
Phase 1: Align the incremental starting point. Run a one-time full-initialization strategy to pour all historically audited return orders in, establishing the "water line" for incremental sync. A common pitfall here is forgetting to carry "last modified time" into the initialization, which causes the later incremental run to pull the same data again.
Phase 2: Bring up incremental scheduling. Schedule runs every 15 minutes with the filter "modified time > last successful time AND document status = approved." In Qeasy, set this as a cron expression with 3 automatic retries and exponential backoff.
Phase 3: Full reconciliation fallback. Run a full reconciliation once daily in the early morning, comparing document numbers and amounts on both sides. Deltas land in an exception table for manual review and re-injection. This is a classic dual-track of incremental plus full—on Qeasy you simply configure two strategies, one for incremental and one for full, so they never interfere with each other.
Pitfalls and Lessons Learned
- Classic mistake: using warehouse code as SKU code. We saw this on a customer site—the codes had the same length and prefix, the mapping table had no uniqueness check, and three months later the inventory on both sides did not match. The safe approach is to add uniqueness checks in the mapping table and attach a business prefix to every field.
- Stage header and line item sync separately. A return order has a clear header-line structure; do not try to handle it all with one interface call. Land the header first, then push line items in batch. Failures can then be pinpointed from "the whole document failed" down to "one specific field on one specific row."
- Ignore the "voided" status. In the WMS, return orders have both "reversed" and "voided" statuses, but the ERP expects "reversed" rather than "voided." Skipping this judgment and pushing as-is will definitely get you called in by finance at month-end close.
- Overlapping time windows. If the incremental strategy uses "poll every 15 minutes, filter modified time > now - 15 minutes," cross-timezone or scheduling delay can cause missed records. The safer pattern is "modified time > last successful timestamp" rather than "now - window."
- Amount precision drift. The WMS stores amounts in yuan with two decimals; the ERP stores them in cents as integers. The middle layer must perform explicit unit conversion, otherwise reconciliation will always be off by a few cents.
When This Applies and When It Does Not
Applies: e-commerce or retail scenarios where the WMS handles front-end documents and the ERP handles finance and inventory, with daily volumes in the low thousands and return frequency lower than order frequency. Does not apply: cross-entity returns (which require inter-company settlement first) and scenarios requiring real-time online inventory writeback—the latter should use an instant-inventory sync strategy, not a document sync strategy.