7 Things That Break NetSuite-WooCommerce Integrations
- Non-idempotent order creation causes duplicate Sales Orders on retry.
- Syncing qty_on_hand instead of qty_available oversells committed stock.
- Country code mismatches (ISO-2 vs full name) silently break address fields.
- NetSuite governance budget exhaustion stops batch jobs mid-run without obvious errors.
- Missing item types (Kit, Matrix, Assembly) not handled by the integration cause silent failures.
NetSuite-to-WooCommerce integrations fail in predictable ways. After running these integrations in production across dozens of merchant accounts, the same seven problems appear repeatedly. None of them are exotic. All of them are avoidable if you know where to look.
1. Non-Idempotent Order Creation (Duplicate Sales Orders)
When WooCommerce sends an order to NetSuite and the API call times out before a response arrives, the integration retries. If the order creation logic does not first check whether a Sales Order with that WooCommerce order ID already exists, the retry creates a second SO — which then gets fulfilled and billed separately.
Every order creation must be idempotent:
Before inserting a new NetSuite Sales Order, search for an existing SO where custbody_wc_order_id = [WC order ID]. If found, skip creation and return the existing SO internal ID. This check adds one SuiteQL query per order but eliminates the most expensive production incident type.
2. Syncing On-Hand Instead of Available Quantity
NetSuite distinguishes quantityOnHand, quantityCommitted, and quantityAvailable. Available = on-hand minus committed. If your integration pushes on-hand to WooCommerce stock, customers can buy units NetSuite has already allocated to open orders. The oversell typically surfaces days later when fulfilment tries to pick the items.
| NetSuite Field | Meaning | Sync to WooCommerce? |
|---|---|---|
| quantityOnHand | Total physical units in warehouse | No — includes committed units |
| quantityCommitted | Units reserved for open SOs | No — used internally |
| quantityAvailable | On-hand minus committed — what can still be sold | Yes — this is the correct field |
| quantityOnOrder | Units on open Purchase Orders inbound | Optional — if you show “arriving soon” messaging |
3. Country Code Mismatches in Address Fields
WooCommerce uses ISO 3166-1 alpha-2 country codes (“US”, “GB”, “DE”). NetSuite address fields expect the full country name (“United States”, “United Kingdom”, “Germany”). Passing “US” directly into the NetSuite country field either fails validation or sets the country to blank — which then fails tax calculation silently.
Fix: Maintain a static country code mapping table in your integration. Map WooCommerce ISO-2 codes to NetSuite country names before every address write. The list is stable — it changes maybe once per decade when countries rename.
4. NetSuite Governance Exhaustion in Batch Jobs
Each SuiteScript scheduled script gets 10,000 governance units. A search.run() call costs 10 units. An https.get() call costs 10 units. Loading a record for update costs 10 units. A batch job processing 500 orders might consume 20,000+ units — double the budget — and terminate silently at the halfway mark. The second 250 orders look like they were skipped with no error logged.
How to detect governance exhaustion:
Add a governance check at the top of every batch loop iteration: runtime.getCurrentScript().getRemainingUsage(). If remaining usage drops below 1,000, log a warning, record the last processed record ID, and exit cleanly. Use a Map/Reduce script for any batch job touching more than 200 records.
5. Unhandled Item Types (Kit, Matrix, Assembly Items)
Most integration code is built and tested against simple Inventory Items. NetSuite has 12+ item types. Kit/Package Items, Matrix Items, and Assembly Items have different field structures, different inventory behaviour, and different SO line item representations. An integration that only handles Inventory Items silently skips or mishandles these types in production.
Run a SuiteQL query: SELECT type, COUNT(*) FROM item WHERE isinactive = 'F' GROUP BY type. Know exactly what types your catalog contains before writing integration code.
Write separate logic branches for each item type your catalog uses. If a type is unsupported, log it and skip rather than letting it cause a partial failure that corrupts downstream data.
WooCommerce variable products map to NetSuite Matrix Items. The parent WooCommerce product maps to the Matrix parent; each variation maps to a Matrix sub-item. Never map variations to the parent Matrix Item’s SKU.
6. Webhook Delivery Failures with No Retry
WooCommerce webhooks use HTTP POST with a 5-second timeout. If your integration endpoint takes longer than 5 seconds to respond (common when it synchronously calls NetSuite), WooCommerce marks the webhook as failed and retries — but only for a limited number of attempts. After the retry limit, the webhook is disabled and orders stop syncing silently.
Respond immediately, process asynchronously:
Your webhook endpoint should return HTTP 200 within 500ms without calling NetSuite. Queue the payload for background processing. This eliminates timeout failures and decouples order volume from API latency.
7. Missing Tax Configuration Causes SO Validation Failures
NetSuite Sales Orders require a Tax Code on each line if the account has SuiteTax enabled. If your integration does not pass a tax code, the SO fails validation and returns a 400 error — but only in production accounts where SuiteTax is configured, not in sandbox accounts where it may not be. This creates a “works in sandbox, fails in production” situation that is difficult to diagnose without looking at the NS error response body.
These seven failures are all detectable in staging if you configure your sandbox to mirror production: same item types, SuiteTax enabled, same governance budget, and realistic order volume. Most teams skip this configuration step — which is why the failures surface in production instead.
References
- NetSuite REST Web Services Error CodesOracle NetSuite Help — complete list of REST API error codes and validation failure reasons.
- SuiteScript GovernanceOracle NetSuite Help — governance unit costs per API call type and script execution limits.
- WooCommerce WebhooksWooCommerce.com — webhook delivery mechanism, retry behaviour, and failure handling.
- NetSuite Item Types ReferenceOracle NetSuite Help — matrix items, kit items, assembly items, and their record structure differences.
- NetSuite SuiteTax ConfigurationOracle NetSuite Help — tax code requirements and SuiteTax validation rules affecting Sales Orders.
Frequently asked questions
What causes duplicate sales orders?
Non-idempotent order creation. Without an idempotency key, any retry after a timeout creates a second order in NetSuite.
Why does syncing on-hand quantity cause overselling?
On-hand includes stock already committed to other orders. Available quantity is the number that should drive storefront stock.
What is NetSuite governance exhaustion?
Every script has a usage budget. Batch jobs that do not yield or checkpoint run out mid-run and leave records half-processed.
Leave a Reply