WooCommerce NetSuite integration

What moves between WooCommerce and NetSuite

WooCommerce captures the order and the payment. NetSuite fulfills, invoices and books it. Six flows cover the pair.

Gateway captures are their own mapping. A Stripe capture and a PayPal capture land on different clearing accounts in NetSuite, so that the payout from each gateway can be reconciled against its own deposits. The gateway comes from payment_method, the reference from transaction_id.

Which system owns what

WooCommerce core has no price per customer and no company account: company is a text field inside the billing address. B2B prices in a WooCommerce store come from an extension. Where one is installed, NetSuite price levels are written to that extension's fields. See customer-specific pricing.

What WooCommerce and NetSuite store differently

Guest orders and customers

A guest order has customer_id 0. NetSuite accepts no sales order without a customer. The integration matches on billing email first, creates a customer when there is no match, and uses the company field to decide between a company and an individual. Placing every web customer under one parent customer works until the hierarchy reaches NetSuite's limit of 10,000 customers. The matching chain is described in duplicate customers and orders.

The order itself

{
  "id": 100482,
  "status": "processing",
  "customer_id": 0,
  "prices_include_tax": false,
  "payment_method": "stripe",
  "billing": {
    "company": "Bakker Installatie B.V.",
    "address_1": "Industrieweg 12",
    "postcode": "3542 AD",
    "country": "NL"
  },
  "line_items": [
    { "sku": "TS-BLK-M", "quantity": 3, "subtotal": "33.67", "total": "30.30" }
  ],
  "coupon_lines": [ { "code": "fall10", "discount": "3.37" } ],
  "fee_lines": [ { "name": "Small order fee", "total": "2.50" } ],
  "meta_data": [ { "key": "_po_number", "value": "PO-7781" } ]
}

Four parts of this order have no direct place in NetSuite. coupon_lines needs a discount item. fee_lines needs a non-inventory or other charge item per kind of fee. shipping_lines becomes a ship method and a shipping cost. meta_data holds whatever your plugins added: a PO number, a delivery date, a VAT number. Each key that matters maps to a custom body field such as custbody_po_number or to a custom segment.

Tax and rounding

WooCommerce stores tax per line and per rate, and a store setting decides whether tax is rounded per line or at subtotal level. Three lines of 10.10 at 8.25 percent give 0.83 each when rounded per line: 2.49. Rounded on the subtotal of 30.30 the tax is 2.50. NetSuite recalculates on the sales order unless the integration writes the store's amounts. One cent of difference keeps a deposit from matching its invoice automatically. prices_include_tax adds a second switch: a store that enters prices including tax sends gross prices, and NetSuite expects net. The integration takes WooCommerce's line totals and tax amounts as given and writes them to NetSuite, so both sides show the amount the customer paid. More in money, tax and rounding.

Variable products and matrix items

A variable product has type variable, and its variations are at /products/<id>/variations, each with its own id, sku, regular_price and stock_quantity. A NetSuite matrix has a parent and child items, with at most 2,000 combinations. Order lines carry both product_id and variation_id; the integration maps the variation to the matrix child by SKU and keeps both IDs in an item map. A variation can be saved without a SKU. Those are reported before go-live, since an order line without a SKU cannot be resolved to an item.

One stock number

A product or variation has one stock_quantity, a stock_status of instock, outofstock or onbackorder, and a backorders setting. There is no location. NetSuite has a quantity per location. The integration sums the locations that may fulfill web orders and writes one number. See multi-location inventory.

The technical reality of this pair

Stock, worked through. A store with 1,500 variable products and 12,000 variations looks like 120 batch requests of 100. It is not: the variation batch endpoint is per parent product, /products/<product_id>/variations/batch. A full stock update is 1,500 requests of 8 variations on average. Every request starts WordPress and its plugins on your host. So the integration sends only variations whose quantity changed, and spaces its requests so that checkout keeps its share of the PHP workers. On the NetSuite side the same 12,000 quantities are 12 SuiteQL pages.

Webhooks and polling.

A WooCommerce webhook is signed with X-WC-Webhook-Signature, a base64 HMAC-SHA256 of the payload, and delivered from WordPress's background queue. Any response other than 2xx, 301 or 302 counts as a failure. After five consecutive failures WooCommerce disables the webhook, and its documentation describes no retry. An integration that depends on webhooks alone loses orders the first time its endpoint is unreachable, and stops receiving them altogether a few orders later. Ours accepts the webhook into a queue and also polls GET /wc/v3/orders?modified_after=... with per_page=100. It checks that the webhook is still active and switches it back on. Background in webhooks are not a guarantee.

Orders into NetSuite. NetSuite is the slower side. At 3 seconds per sales order and 2 of the 5 slots of a Standard account, the maximum is 40 orders a minute. External ID WOO-100482 on the sales order makes a retry an update. The numbers are on the NetSuite page and in NetSuite concurrency limits.

Versions. WooCommerce removed its legacy REST API from core in version 9.0. An integration written against /wc-api/v3 stopped working there unless the separate legacy plugin was installed. The current API is /wp-json/wc/v3.

Where standard connectors stop

A standard connector maps the documented order schema: lines, addresses, totals, status. In a WooCommerce store a large part of the order is stored outside that schema, and it differs per store.

• Plugin data in meta_data. Subscriptions, deposits, delivery dates, B2B roles and VAT numbers are stored under keys chosen by each plugin's author. No fixed mapping knows them.
• Tracking. The documented order has no tracking field. The Shipment Tracking extension has its own endpoint, /wc-shipment-tracking/v3/orders/<order_id>/shipment-trackings, and no call to update a tracking item once it exists.
• Refunds that pay out. api_refund is true by default. A connector that mirrors a NetSuite credit memo into a WooCommerce refund without setting it to false triggers the payment gateway.
• Stock per location. With one stock number in WooCommerce, the choice of which NetSuite locations count is a rule that has to be written down somewhere. A fixed setting for one location does not cover a second warehouse.

A built integration starts from an inventory of your plugins and the keys they write. The technical comparison is in custom integration vs iPaaS.

When it goes wrong

An order that still fails after its retries is kept with its payload and can be sent again after the cause is fixed. A WordPress update, a plugin update or a host migration is the usual moment for one of the first four rows; the alert arrives before a customer asks where the order is.

Before go-live the integration runs as a dry run: it reads your live orders and shows the sales orders, customers and deposits it would create in NetSuite, without writing. From then on each run leaves a diff per record in the dashboard. We host and monitor it as part of an e-commerce ERP integration. The WooCommerce page covers the platform side. Sibling pages: Shopify NetSuite integration, Magento NetSuite integration and BigCommerce NetSuite integration. Tell us which plugins your store runs.