NetSuite Integration for WooCommerce

NetSuite Integration for WooCommerce establishes a secure, bidirectional connection between a WooCommerce store and an Oracle NetSuite account. The extension synchronises orders, inventory, pricing, and customer records; supports advanced conditional field mapping (currencies, subsidiaries, shipping and payment methods, sales representatives, classes, and custom fields); and imports products and customers from NetSuite into WooCommerce, removing the need for manual data entry.

All synchronisation runs in the background on a configurable schedule and may also be triggered on demand. A comprehensive activity log records every operation, including the exact request and response exchanged with NetSuite.

Compatibility: WooCommerce 2.2–11.0 · WordPress 5.9 or later (tested to 7.0) · PHP 8.0 or later · WooCommerce High-Performance Order Storage (HPOS): supported

1. Connection Modes

↑ Back to top

The extension communicates with NetSuite through one of two connection modes. The active mode is determined automatically by whether the NetSuite SOAP add-on is active on the site; it is not selected manually.

	REST API (default)	SOAP (legacy)
Applies when	The SOAP add-on is not installed	The SOAP add-on is active
PHP SOAP extension	Not required	Required
NetSuite service	REST Web Services and SuiteQL	SuiteTalk SOAP Web Services
Credential setup	Identical in both modes	Identical in both modes

Identifying the active mode. Open the extension dashboard. Sites operating in SOAP mode display a corresponding notice; if no notice is present, the site is operating in REST mode.

Rationale for REST as the default. REST mode does not depend on the PHP SOAP extension, which is frequently unavailable on shared hosting. It also provides improved throughput for bulk operations and receives new functionality first. Existing SOAP installations continue to operate without modification; migration is not required.

Operational differences. Both modes synchronise the same records and honour the same configuration. The following distinctions apply:

• SOAP mode requires the PHP SOAP extension. If the extension is unavailable, the extension displays a notice and suspends NetSuite operations while the remainder of the site continues to function normally.
• REST mode routes NetSuite requests through a hosted connector service, requiring only standard outbound HTTPS connectivity from the web server.
• The two NetSuite APIs represent certain field types differently. The extension performs this translation automatically; this is, however, why the field type selected in Conditional Mapping must correspond to the field’s configuration in NetSuite. Refer to Section 8.
• Note: Configuration, conditional mapping rules, and stored NetSuite record identifiers are retained when the connection mode changes, as they are stored independently of the connection method. Re-test the connection after switching modes.

2. Synchronisation Scope

↑ Back to top

WooCommerce to NetSuite

WooCommerce record	NetSuite record
Orders	Sales Orders, Cash Sales, Invoices, or Customer Deposits
Customers	Customer records (individual or company), with optional Contact records
Refunds	Return Authorisations

NetSuite to WooCommerce

NetSuite record	WooCommerce record
Inventory and pricing	Product stock levels and prices (multi-location and multi-currency aware)
Items	Products, including titles, descriptions, dimensions, images, and custom fields
Customers	WordPress user accounts
Return Authorisations	Order refunds
Item Fulfilments	Shipment tracking number, carrier, and ship date, with optional customer notification

3. Feature Summary

↑ Back to top

• Order synchronisation as Sales Order, Cash Sale, Invoice, or Customer Deposit, including coupon, tax, shipping, location, and price-level mapping.
• Inventory and price synchronisation on a defined schedule (hourly, twice daily, or daily) or on demand, across all locations, a default location, or a selected subset.
• Product import from NetSuite, including images, galleries, dimensions, and custom fields, with independent create and update control for each field.
• Customer synchronisation to NetSuite as individual or company entities, with duplicate-safe matching by email address and company name, and optional Contact records beneath company customers.
• Customer import from NetSuite into WooCommerce user accounts.
• Bidirectional refund synchronisation between WooCommerce refunds and NetSuite Return Authorisations.
• Shipment tracking synchronisation, with optional customer notification and automatic order completion.
• Conditional field mapping supporting fixed values, WooCommerce field values, and condition-based assignment, together with dedicated shipping- and payment-method mapping. No development work is required.
• Encrypted credential storage, comprehensive API logging, configuration import and export, and WooCommerce HPOS compatibility.

4. Requirements

↑ Back to top

Requirement	Detail
WooCommerce	2.2 or later
WordPress	5.9 or later
PHP	8.0 or later
PHP SOAP extension	Required for SOAP mode only
NetSuite account	Token-Based Authentication enabled, with administrative access to create credentials
NetSuite REST Web Services	Required for order and customer synchronisation in REST mode, and for Product Import and Customer Import in both modes
NetSuite SuiteTalk SOAP Web Services	Required for SOAP mode only

No RESTlet or SuiteScript deployment is required for any feature.

5. Installation and Connection

↑ Back to top

5.1 Installation

Upload and activate the extension, then open NetSuite Integration in the WordPress administration menu. Sites operating in SOAP mode without the PHP SOAP extension will display a notice; the extension must be enabled by the hosting provider before synchronisation can proceed. This requirement does not apply to REST mode.

5.2 Establishing the connection

↑ Back to top

The extension authenticates using NetSuite Token-Based Authentication (TBA). Six values are required: Host URL, Account ID, Consumer Key, Consumer Secret, Token ID, and Token Secret.

1. Host URL and Account ID. In NetSuite, navigate to Setup → Company → Company Information. Record the Account ID, and under Company URLs, record the SuiteTalk (SOAP and REST Web Services) URL.
2. Consumer Key and Consumer Secret. Navigate to Setup → Integration → Manage Integrations → New. Provide a name for the integration record. Clear the TBA: Authorization Flow and Authorization Code Grant options, and select Token-Based Authentication and User Credentials. Save the record and retain the Consumer Key and Consumer Secret, which are displayed only once.
3. Token ID and Token Secret. Navigate to Home → Manage Access Tokens → New My Access Token. Select the integration record created above and save. Retain the Token ID and Token Secret, which are displayed only once.
4. Signature method. Select HMAC-SHA256 and save the configuration.
5. Select Test API Credentials. A successful connection returns the confirmation message “Congrats. API connection is successful.”

Consumer and Token secrets are encrypted at rest and are never stored in plain text.

Important: If the connection test fails while the credentials are known to be valid, the cause is most commonly an insufficient NetSuite role permission rather than an incorrect credential. The SuiteAnalytics Workbook permission is required by the connection test. Refer to Section 5.3.

5.3 Required NetSuite role permissions

↑ Back to top

In NetSuite, navigate to Setup → User Roles → Manage Roles and assign the following permissions to the role used for the integration.

NetSuite tab	Permission	Level
Transactions	Sales Order	Full
Transactions	Item Fulfillment	Full
Transactions	Fulfill Sales Order	Full
Transactions	Cash Sales	Full
Transactions	Find Transaction	Full
Reports	SuiteAnalytics Workbook	Full
Lists	Items	View
Lists	Location	View
Lists	Currency	View
Lists	Promotions	Full
Lists	Shipping Items	View
Lists	Customer	Full
Lists	Units	Full
Setup	REST Web Services	Full
Setup	User Access Tokens	Full
Setup	Integration Application	Full
Setup	SOAP Web Services	Full
Setup	Accounting Lists	Full

Note (REST mode): To synchronise the order payment method, enable the Payment Instruments feature in NetSuite and grant the Payment Instruments permission at Full level to the integration role. Refer to Section 7.2.

6. Inventory and Price Synchronisation

↑ Back to top

Setting	Description
Stock Sync	Enables inventory synchronisation and sets the frequency (hourly, twice daily, or daily).
Inventory Location	All locations, the default location, or a selected subset. Quantities across multiple locations are aggregated.
Inventory Quantity Field	Quantity on Hand or Quantity Available.
Override Manage Stock	Determines whether quantities are applied to products that do not have stock management enabled.
Update Stock Status	Determines whether the WooCommerce stock status is updated alongside the quantity.
Price Sync	Enables price synchronisation and selects the NetSuite Price Level.
SKU mapping field	Determines which NetSuite field is matched against the WooCommerce SKU. Refer to Section 6.1.

Select Manual update inventory and(or) price to run an immediate synchronisation.

6.1 SKU mapping field

This setting determines which NetSuite item field is compared against the WooCommerce SKU. It governs inventory synchronisation, price synchronisation, and order line-item resolution.

Option	Matched against
Item ID	The item’s Name/Number field (most common)
UPC Code	The item’s UPC Code field
Display Name/Code	The item’s Display Name field
Vendor Name/Code	The item’s Vendor Name field
Custom Field	A custom item field, specified by its NetSuite field identifier

Important: If the selected field does not correspond to the location of SKU values within NetSuite, no records will match. Inventory synchronisation will report zero updates, and order synchronisation will fail with “No order lines could be mapped to NetSuite items.” To verify, open any item in NetSuite and compare the selected field against the corresponding WooCommerce SKU.

7. Order Synchronisation

↑ Back to top

Configure under Order Settings → General.

Setting	Description
Order Sync	Enables order synchronisation.
Sync Order As	Determines the NetSuite record type created: Sales Order or Cash Sale.
Sync Orders Status	The WooCommerce order status that triggers synchronisation. Defaults to Processing.
Create Woo Orders Deposit	Creates a Customer Deposit alongside the Sales Order.
Auto Create Invoice	Generates an Invoice when the order reaches a specified status.
Order Delete on NetSuite on WC Delete	Removes the corresponding NetSuite record when a WooCommerce order is deleted.
Coupon Sync	Transfers applied coupons to NetSuite as promotions. Requires the SuitePromotions and Promotion Codes features.
Display Tracking Number	Displays the tracking number in the customer account area.

Under Order Settings → Line Items, configure the shipping line-item internal identifier, line-item location, price level, and tax code.

Each synchronised order is recorded with its NetSuite identifier, preventing duplicate creation on subsequent synchronisation.

7.1 Cash Sale configuration

↑ Back to top

Where Sync Order As is set to Cash Sale, NetSuite requires the posting account to be determinable. If it is not, order creation fails with “Please enter a value for Account.”

Define the following conditional mapping rules on the Order tab:

Field	Type	Value
paymentOption	Record reference	Internal identifier of the payment method
undepFunds	Boolean	false to post to a bank account; true to post to Undeposited Funds
account	Record reference	Bank account internal identifier, where it cannot be derived from the payment method

Note: The value assigned to undepFunds determines the accounting treatment of received funds and should be confirmed with the personnel responsible for the NetSuite general ledger.

7.2 Payment method

↑ Back to top

The order’s payment method is assigned to the NetSuite paymentOption field using a conditional mapping rule of type Record reference, with the internal identifier of the corresponding NetSuite payment method as the value. Where several WooCommerce gateways are in use, create one Set when rule for each, conditional on the WooCommerce payment method.

Important (REST mode): Before payment methods can be synchronised in REST mode, enable the Payment Instruments feature in NetSuite (Setup → Company → Enable Features) and grant the Payment Instruments permission at Full level to the integration role (Setup → User Roles → Manage Roles). Until both are in place, NetSuite rejects the payment method value and the field remains unpopulated. This step does not apply to SOAP mode.

8. Conditional Mapping

↑ Back to top

Conditional mapping assigns additional values to NetSuite records without requiring development work. It is available for both order and customer synchronisation. Each rule takes one of three forms:

Rule type	Behaviour
Always set	Assigns a fixed value on every synchronisation.
Set when	Assigns a fixed value only where a WooCommerce field satisfies a specified condition (IS, IS NOT, CONTAINS, DOES NOT CONTAIN).
Copy from Woo	Copies a WooCommerce value directly, with an optional prefix (for example, +91 for telephone numbers or WC- for reference numbers).

Rules are evaluated in order from top to bottom; where multiple rules target the same field, the last rule evaluated takes precedence. The Skip when updating option restricts a rule to the initial synchronisation only.

8.1 Selecting the correct field type

↑ Back to top

Selecting a field type that does not correspond to the field’s configuration in NetSuite will cause the value to be disregarded. NetSuite does not return an error in this circumstance; the field simply remains unpopulated.

First, select the field category:

• Standard field. A built-in NetSuite field, such as memo, shipMethod, or department. Select the field from the list; the type is determined automatically.
• Custom field. A field defined within the NetSuite account, prefixed custbody, custcol, or custentity. Enter the field identifier and select the type corresponding to its NetSuite configuration.

For custom fields, select the type according to the field’s Type in NetSuite (Customization → Transaction Body Fields):

NetSuite field type	Select	Value format
Free-Form Text, Text Area, Long Text	Text	Text value
Decimal, Currency, Integer	Number / Decimal / Currency	Numeric value
List/Record referencing a custom list	Select	Internal identifier of the list entry
List/Record referencing a record type	Record reference	Internal identifier of the record
Multiple Select	Multi-select	Comma-separated names (see note below)
Check Box	Boolean	true or false
Date, Date/Time	Date / time	Date value

Note: Multiple Select fields are the sole exception to identifier-based referencing. NetSuite resolves multi-select values by name, and the value must match exactly. All other reference types use the record’s internal identifier.

Values referencing NetSuite records must be supplied as internal identifiers rather than display names. Internal identifiers are visible on the record within NetSuite; if they are not displayed, enable Home → Set Preferences → Show Internal IDs.

9. Customer Synchronisation

↑ Back to top

Configure under Customer Settings.

Setting	Description
Enable Customer Sync	Enables synchronisation on registration, profile update, and order placement.
Sync these user roles	Restricts synchronisation to users holding a selected WordPress role. Users without a selected role are not transmitted to NetSuite.
Send Customers as Company	Creates company entities rather than individuals, either for all customers or only where the billing address includes a company name. Where no company name is present, the customer’s first and last name are used.
Also create a contact record	Creates a NetSuite Contact beneath the company customer, suitable for business accounts with multiple contacts. Contacts are matched by email address before creation, preventing duplicates on subsequent synchronisation.
Customer entity ID	NetSuite auto permits NetSuite to assign the Entity ID; Use email submits the customer’s email address. A conditional mapping rule targeting entityId overrides both options.
Match existing customers by	Determines how an existing NetSuite customer is identified before a new record is created: email address, company name, or both.
Update behaviour	Create + update refreshes existing NetSuite customers; Only create new leaves existing records unmodified.

10. Product Import

↑ Back to top

Product Import creates and updates WooCommerce products from NetSuite items using the NetSuite REST Web Services connection. No SuiteScript or RESTlet deployment is required. Configure under Product Import.

Setting	Description
Sync products from NetSuite	Enables product import. Creates new products and updates existing products according to the field mapping.
Import only modified products	Restricts subsequent runs to products modified since the previous import. The initial run retrieves all products.
Filter by NetSuite field	Restricts import to products where a specified NetSuite checkbox field is selected (for example, isonline). Accepts 1, true, yes, or on. Leave blank to import all products.
Status for new / updated products	Draft or Published.
Item types to sync	Inventory items, assembly items, or both.
How often to sync	Schedule for automatic import.
Import products now	Queues an immediate background import.

Field mapping. Each WooCommerce field is mapped to a NetSuite field identifier, with independent Create and Update control — for example, Title to itemid, Description to purchasedescription, Weight to weight, and Product image to storedisplayimage. Additional fields may be mapped using Add custom field mapping. Images are downloaded and attached to the product, and are re-downloaded only when the source image changes.

11. Customer Import

↑ Back to top

Customer Import creates WordPress user accounts from NetSuite customer records using the NetSuite REST Web Services connection. No RESTlet or SuiteScript deployment is required.

• Import individuals, companies, or both, with optional filtering by a NetSuite custom field.
• Restrict subsequent runs to records modified since the previous import.
• Generate or map passwords, with an optional welcome notification.
• Run on a defined schedule or on demand using Import Now.

Imported data includes email address, username, name, telephone number, company, complete billing and shipping addresses, and any mapped custom fields.

12. Refund Synchronisation

↑ Back to top

Configure under Order Settings → Refunds. Each direction may be enabled independently.

Direction	Behaviour
WooCommerce to NetSuite	A WooCommerce refund creates a corresponding NetSuite Return Authorisation.
NetSuite to WooCommerce	A Return Authorisation creates a corresponding WooCommerce refund, following the NetSuite sequence of Fulfil, Authorise Return, Receive, and Refund.

13. Order Tracking and Fulfilment

↑ Back to top

Configure under Order Settings → Fulfilment.

Setting	Description
Fulfilment Sync	Retrieves fulfilment records from NetSuite and applies them to WooCommerce orders.
Mark Order as Completed	Sets the order status to Completed when NetSuite reports the order as billed or fulfilled.
Send Order Tracking Email to Customer	Sends a tracking notification. Sent once per order.
Tracking meta keys	Determines the order meta keys used to store the tracking number, shipping carrier, and ship or pickup date.

14. Logging, Import, and Export

↑ Back to top

NetSuite API Logs. Every operation is recorded, covering orders, customers, products, inventory, pricing, refunds, and tracking. Each entry includes a timestamp and the response returned by NetSuite. Individual entries provide the complete request and response payloads for download, which is the most direct method of establishing what was transmitted.

Configuration import and export. Configuration may be exported for backup purposes or transferred between staging and production environments. The export includes all settings together with order and customer conditional mapping rules.

Important: Exported files contain NetSuite credentials and should be handled with the same care as passwords. Importing a configuration file originating from a different NetSuite account will overwrite the existing connection settings.

15. Frequently Asked Questions

↑ Back to top

Does the extension synchronise in both directions? Yes. Orders, customers, and refunds are transmitted to NetSuite. Inventory, pricing, products, customers, tracking, and refunds are retrieved from NetSuite.

Does the extension use the REST API or SOAP? REST by default. SOAP is used only where the NetSuite SOAP add-on is active. Refer to Section 1.

Is the PHP SOAP extension required? Only in SOAP mode. REST mode does not require it.

Can products and customers be imported from NetSuite? Yes. Both use the existing NetSuite REST Web Services connection and support field mapping and scheduling.

Can customers be synchronised as companies for business accounts? Yes, either for all customers or only for those with a company name in the billing address. Contact records may optionally be created beneath the company.

Will duplicate records be created? No. Records are tagged with their NetSuite identifier and matched by email address or company name before creation.

How frequently is inventory updated? Hourly, twice daily, or daily, with on-demand synchronisation also available.

Is the extension compatible with HPOS? Yes.

Is the connection secure? Yes. The extension uses NetSuite Token-Based Authentication, and secrets are encrypted at rest.

What occurs if the PHP SOAP extension is unavailable? In SOAP mode, the extension displays a notice and suspends NetSuite operations while the site continues to function normally. REST mode is unaffected.

16. Troubleshooting

↑ Back to top

Symptom	Resolution
Connection test fails although credentials are verified as correct	Assign the SuiteAnalytics Workbook permission (Full) to the NetSuite role used by the integration. This permission is required by the connection test.
“You must enter at least one line item”	Correct the SKU mapping field so that it corresponds to the NetSuite field containing the SKU values.
“No order lines could be mapped to NetSuite items”	As above. Alternatively, the referenced items do not exist in NetSuite.
Inventory synchronisation completes with zero updates	The SKU mapping field does not correspond to the NetSuite field containing SKU values, or the items hold no stock in the selected locations.
“Does not have the required permissions to access [list]”	Assign the missing permission to the NetSuite role used by the integration.
“Do not have permissions to set a value for element entityid”	Set Customer entity ID to NetSuite auto under Customer Settings.
“Invalid item reference key … for subsidiary …”	Ensure the customer and the items are assigned to the same NetSuite subsidiary.
“Please enter value(s) for: …”	Populate the required field using a conditional mapping rule.
“Please enter a value for Account”	Cash Sale orders require paymentOption and undepFunds to be defined. Refer to Section 7.1.
“Please enter value(s) for: Tax Code”	NetSuite cannot derive a tax code through the API, although the user interface populates it automatically. Define a tax code under Order Settings → Line Items, or assign a default tax item to the customer and a tax schedule to the item for the applicable nexus.
“Cannot create transactions with Stackable Promotions when SuitePromotions disabled”	Enable the SuitePromotions feature in NetSuite, or disable Coupon Sync.
“Promotion Codes feature not enabled”	Enable the Promotion Codes feature in NetSuite.
“You must create a purchase order first to transfer intercompany inventory”	The order’s subsidiary and the item’s stocking location belong to different subsidiaries. Align the two, or assign the order’s subsidiary using a conditional mapping rule.
A conditional mapping rule saves successfully but the NetSuite field remains empty	The selected field type does not correspond to the field’s configuration in NetSuite. NetSuite disregards mismatched values without returning an error. Refer to Section 8.1.
Order synchronisation times out	Order synchronisation performs several NetSuite operations within a single request. Ensure the latest version of the extension is installed, which permits additional time for this sequence.
The payment method is not populated in NetSuite (REST mode)	Enable the Payment Instruments feature in NetSuite and grant the Payment Instruments permission (Full) to the integration role. Refer to Section 7.2.
Product or customer import does not run	Confirm that REST Web Services is enabled in NetSuite and that the role used by the integration holds REST Web Services (Full). Re-test the connection.

Configure under Inventory Settings.

---

---

Developed by TechMarbles. For support, use the Help & Support tab in the plugin.