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 topThe 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. Any active plugin whose name contains both “netsuite” and “addon” switches the whole site to SOAP mode.
| 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. Imports and stock and price synchronisation normally fetch their data over outbound HTTPS. If that fails, the connector sends the data to the site instead, which requires inbound access to
/wp-json/tmwni/; firewalls, CDN challenges, security plugins, and password-protected staging sites can block it. - 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. REST mode does not keep the credentials in WordPress, so switching from REST to SOAP requires entering them again; switching from SOAP to REST uploads the saved credentials automatically. Re-test the connection after switching modes.
2. Synchronisation Scope
↑ Back to topWooCommerce 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 |
| Coupons (SOAP mode) | Promotion Codes with the same code (Section 7) |
NetSuite to WooCommerce
| NetSuite record | WooCommerce record |
| Inventory and pricing | Product stock levels and prices (multi-location and multi-currency aware). Refer to Section 6. |
| Items | Products, through Product Import (Section 10): simple, variable (REST mode), and grouped 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 |
Products travel in one direction only: from NetSuite to WooCommerce. WooCommerce products, prices, and stock levels are never created or updated in NetSuite.
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. Matrix items can import as variable products (REST mode), and group items as grouped products.
- 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.
- Dashboard with synchronisation totals, recent orders, and one-click resubmission of failed orders.
- Automatic recovery: an hourly check re-sends recent orders that did not reach NetSuite, and throttled requests are retried.
- 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 every feature in REST mode. In SOAP mode, required for stock and price synchronisation, order item lookup, Product Import, and Customer Import |
| NetSuite SuiteTalk SOAP Web Services | Required for SOAP mode only |
| Background processing | Synchronisation runs as WooCommerce Scheduled Actions, so WP-Cron or a server cron must run. A manual stock and price synchronisation also requires the site to be able to send requests to itself (check Tools → Site Health in WordPress) |
| PHP OpenSSL extension | Required to encrypt stored SOAP-mode credentials |
No RESTlet or SuiteScript deployment is required for any feature. WooCommerce must remain active: if it is deactivated, the extension deactivates itself and must be reactivated afterwards.
5. Installation and Connection
↑ Back to top5.1 Installation
↑ Back to topUpload and activate the extension, then open TM NetSuite in the WordPress administration menu. On first use, a setup wizard guides the connection step by step; it may be skipped and the connection entered manually as described below. The wizard saves the connection together with three inventory defaults (SKU mapping field, price level, and currency); its What should sync? choices do not switch anything on, so enable each synchronisation on its own page afterwards.
Sites activated without the PHP SOAP extension display a notice for up to a week. In SOAP mode, the extension must be enabled by the hosting provider before synchronisation can proceed; REST-mode sites can ignore the notice.
5.2 Establishing the connection
↑ Back to topThe 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. Enter them under Sync → Setup, in the API credentials panel. Only administrators can test the connection or view the stored credentials.
- 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.
- 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.
- 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.
- Enter the credentials. Enter all six values in the API credentials panel. Requests are signed with HMAC-SHA256 automatically; no signature method needs to be selected.
- Test and save. Select Test connection. In REST mode, a successful test displays “Connected to NetSuite” together with the message “Congrats. NetSuite credentials validated and saved successfully.” In REST mode, a successful test also saves the credentials on the connector immediately. In SOAP mode, the test confirms only that all six fields are completed. Save Changes tests the credentials again before saving; credentials that fail the test are never stored.
To repeat the guided setup at any time, select Run setup wizard on the Setup page.
In REST mode, the credentials are held by the hosted connector service, and WordPress stores only a reference key. Saved secrets are displayed masked (only the first and last four characters are shown); to change any connection value, enter all four keys and secrets again. In SOAP mode, the credentials are stored in the WordPress database, with the keys, tokens, and secrets encrypted.
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. Where the test reports a hosting problem (a timeout, DNS, or SSL failure) instead, the credentials have not been tested: select Copy message for your host and send the message to the hosting provider.
5.3 Required NetSuite role permissions
↑ Back to topIn 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.
5.4 Admin pages
↑ Back to topThe extension adds a single page to the WordPress administration menu, TM NetSuite, with a sidebar on the left. The navigation paths in this guide start from that sidebar.
| Sidebar | Page | Purpose | Section |
| Dashboard | Dashboard | Synchronisation totals and recent orders | 5.5 |
| Sync → Setup | NetSuite connection | Connection credentials and the setup wizard | 5.2 |
| Sync → Inventory | Inventory & price sync | Stock and price synchronisation, and the SKU mapping field | 6 |
| Sync → Customers | Customer settings | Customer synchronisation to NetSuite (Woo → NetSuite tab) and customer import (NetSuite → Woo tab) | 9, 11 |
| Sync → Orders | Order settings | Orders, line items, and order conditional mapping (Export (Woo → NetSuite) tab), refunds (Refunds tab), and tracking (Fulfillment tab) | 7, 8, 12, 13 |
| Sync → Products | Product settings | Product import and product field mapping | 10 |
| Tools → Import / Export | Import & Export | Configuration backup and transfer | 14 |
| Tools → Logs | Sync logs | Activity log, with request and response downloads | 14 |
| Tools → Help | Help & support | Support contacts and resources | — |
On the Inventory, Customers, Orders, and Products pages, settings are grouped into collapsible sections, each with its own Save button. A section’s Save button becomes available once something in that section changes (Unsaved changes in this section); changes that have not been saved are not applied. The Setup page uses a single Save Changes button.
5.5 Dashboard
↑ Back to topThe Dashboard summarises synchronisation activity:
- Tiles for orders synchronised, customers synchronised, when inventory was last synchronised (the start of the last scheduled run, in UTC; manual runs do not change it), and failed orders among the recent entries.
- Recent orders, with All, Synced, and Not synced tabs and a search box. The list shows orders the extension has attempted to send; hover over a failed order to see the reason.
- Resubmit sends an order to NetSuite immediately, even when automatic order synchronisation is switched off. Cancelled, refunded, failed, and trashed orders are not resubmitted.
- Open in NetSuite opens the synchronised record in NetSuite.
5.6 Background processing
↑ Back to topSynchronisation runs in the background as WooCommerce Scheduled Actions, listed under WooCommerce → Status → Scheduled Actions in the group tmwni. Where no frequency is selected, product import runs daily, and customer import and stock and price synchronisation run hourly. In REST mode, when the connector service turns a request away because of rate limits, the request is retried up to three times. Errors returned by NetSuite are not retried, except for orders, which the hourly catch-up re-sends (Section 7). Deactivating the extension stops all schedules.
5.7 Plugins screen and uninstalling
↑ Back to topOn the WordPress Plugins screen, the extension provides Settings, View details (including the full changelog), Website, Support, Email us, and Book a call links.
Deleting the extension from the Plugins screen removes its settings, conditional mapping rules, logs, request and response files, and database tables, together with the stored connection key, so the credentials must be entered again after reinstalling. It also removes the NetSuite links stored on products and users and, on orders where WooCommerce does not use High-Performance Order Storage, the NetSuite links and the tracking numbers stored in the YITH order-tracking field. Order data held in High-Performance Order Storage is kept.
6. Inventory and Price Synchronisation
↑ Back to topConfigure under Sync → Inventory. Stock levels and prices are retrieved for published WooCommerce products and enabled variations that have a SKU; products saved as Draft, Pending review, or Private (for example by Product Import) receive no stock or price until they are published. Stock changes made by the synchronisation do not send WooCommerce’s low-stock or out-of-stock emails.
Common settings (apply to both stock and price synchronisation)
| Setting | Description |
| SKU mapping field | Determines which NetSuite field is matched against the WooCommerce SKU. Refer to Section 6.1. |
| Custom field internal ID | Appears when SKU mapping field is set to Custom Field. The identifier of the NetSuite custom item field that holds the SKU, for example custitem_sku. |
| Automatic sync frequency | How often stock and prices are synchronised: Hourly, Twice Daily, or Daily. |
Stock management
| Setting | Description |
| Enable stock sync | Enables scheduled stock synchronisation from NetSuite. |
| Force enable WooCommerce stock management | Turns on WooCommerce’s Manage stock option for each product that receives a quantity from NetSuite. Applies only when Enable stock sync is on. |
| Update stock status | Sets each product to In stock or Out of stock according to the synchronised quantity. Products set to On backorder are left unchanged. |
| Sync unit conversions | Converts NetSuite quantities, which are held in each item’s base unit, into the item’s stock unit using the NetSuite conversion rate. For example, 120 units of an item stocked in cases of 12 become a quantity of 10. Currently applies in SOAP mode only. |
| Set stock to 0 when NetSuite reports 0 | When NetSuite reports no stock for an item, sets the WooCommerce quantity to 0. When off, a zero quantity leaves the existing WooCommerce quantity unchanged, although Update stock status may still mark the product as out of stock. |
| Quantity field | Quantity available (sellable stock) or Quantity on hand (everything in the warehouse). The field starts empty; select one explicitly. |
| Item types to sync | Inventory item, Assembly item, or both. At least one must remain selected. Clear Assembly item if the NetSuite account does not use the Assembly Items feature. |
| Inventory location | All locations, Default (the location set on each item in NetSuite), or Custom (the locations selected in Custom locations). Quantities across multiple locations are aggregated. |
| Custom locations | Appears when Inventory location is set to Custom. Select one or more NetSuite locations; at least one is required. |
Price management
| Setting | Description |
| Enable price sync | Enables scheduled price synchronisation from NetSuite. |
| Price level | The NetSuite price level written to WooCommerce, for example Base Price or Online Price. The price is applied as the product’s regular price; a sale price set in WooCommerce is left unchanged. |
| Price currency | The NetSuite currency to read prices in. Select the store’s WooCommerce currency; prices are not converted. |
The lists of locations, price levels, and currencies are retrieved from NetSuite. Select the refresh button beside a list to retrieve it again.
One-off actions
- Run manual sync runs an immediate stock and price synchronisation and displays a progress bar with live stock and price logs. Enable stock sync or Enable price sync must be switched on and saved first. If nothing was updated, the result explains why, for example that the synchronisation was blocked by a firewall or CDN, or that the site cannot run background tasks.
- Remove NetSuite IDs deletes the NetSuite item links stored against WooCommerce products. Use it when products are linked to the wrong NetSuite items, for example after changing the SKU mapping field or connecting a different NetSuite account; products are matched by SKU again afterwards. This action cannot be undone.
6.1 SKU mapping field
↑ Back to topThis setting determines which NetSuite item field is compared against the WooCommerce SKU. It governs inventory synchronisation, price synchronisation, order line-item resolution, and Product Import, which uses it to match existing products, as the SKU of new products, and to link group members. If it is not set, Product Import imports nothing.
| Option | Matched against |
| Item Name / Number | 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 in Custom field internal ID |
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 topConfigure under Sync → Orders → Export (Woo → NetSuite), in the General section.
| Setting | Description |
| Enable order sync | Enables order synchronisation. When off, orders are not sent to NetSuite automatically. |
| Order record type | Determines the NetSuite record type created: SalesOrder or CashSale. The customer deposit, invoice, and fulfilment options are available only for SalesOrder. |
| Auto-sync on WooCommerce status | The WooCommerce order status at which an order is first sent to NetSuite, for example Processing. Always select a status. With Pending payment, only orders placed through the classic checkout are sent immediately; orders from the block checkout or created in the admin are sent by the hourly catch-up. |
| Also auto-sync on these status changes | Additional status changes that send an order to NetSuite: On Hold → Processing, Pending → Processing, On Hold → Completed, and Processing → Completed. An order is sent only if it has not already been synchronised; an order that already exists in NetSuite is not sent again. |
| Create customer deposit on sync | SalesOrder only. Creates a Customer Deposit in NetSuite for the amount paid, alongside the Sales Order. |
| Auto-generate invoice | SalesOrder only. Creates a NetSuite Invoice when the order reaches the status selected in Invoice on this WooCommerce status. In REST mode, select an invoice status that comes after the auto-sync status (for example, auto-sync on Processing and invoice on Completed); no invoice is created when the two are the same. |
| Sync deleted/trashed orders | When a synchronised order is moved to the Trash or permanently deleted in WooCommerce, deletes the corresponding NetSuite record. Restoring the order from the Trash does not recreate it in NetSuite. Cancelling an order does not change NetSuite. |
| Sync coupons as discount items | Sends the order’s coupon discount to NetSuite using the item selected in NetSuite discount item, which is required. In REST mode, the discount is added to the order as a discount line. In SOAP mode, each coupon is applied as a NetSuite promotion code, which requires the SuitePromotions and Promotion Codes features. |
| Display NetSuite order tracking number | Adds a Tracking Number column to the customer’s My Account → Orders list. The column appears only when at least one setting on the Fulfillment tab is switched on. Refer to Section 13. |
| Email admin on sync failure | Sends an email to the address entered in Admin email when an order fails to synchronise. |
Line items. The Line items section on the same tab determines how order lines are presented in NetSuite.
| Setting | Description |
| Add shipping as a line item | Adds the order’s shipping charge as a separate line, using the NetSuite item whose internal identifier is entered in NetSuite shipping item. |
| Sync Woo tax rate as line item | Adds the order’s total tax as a separate line, using the NetSuite item whose internal identifier is entered in NetSuite tax item (line item). |
| Item location | The location assigned to each line: No default location (no location is sent), Default item location (the NetSuite location recorded for each product), or Custom location (the single location selected in Custom location, applied to every line). |
| Send price level on items | Assigns the selected Price level to each line. Line amounts remain the WooCommerce amounts. To keep WooCommerce pricing rather than a NetSuite price level, select Custom Price Level together with Send line-item unit rate. |
| Send line-item unit rate | Applies together with Send price level on items: also sends the WooCommerce unit price as each line’s rate. Where no price level is sent, the unit price is always sent. |
| Apply tax code to items | Assigns the selected Tax code to every line. |
| Send Tax Amount from WooCommerce | Applies together with Apply tax code to items: also sends the tax amount WooCommerce calculated for each line. |
Each synchronised order is recorded with its NetSuite identifier, preventing duplicate creation on subsequent synchronisation. If the connection drops before NetSuite replies, the extension looks the order up in NetSuite and records it as synchronised when it was created.
On the order screen. The NetSuite Sales Order Synchronization box shows whether the order has been synchronised, with its NetSuite internal ID and, where created, the invoice ID. To send an order immediately, select Sync to NetSuite under Order actions; on an order that is already synchronised, this updates the NetSuite record. The action appears only while Enable order sync is on, and cancelled, refunded, and failed orders, and orders from roles that are not synchronised, are skipped.
Hourly catch-up. While order synchronisation is enabled, an hourly check re-sends orders that have no NetSuite identifier, are in a status selected for synchronisation, and were created within the last two hours (up to 200 orders per run). It covers orders that were missed or failed. Its results are recorded in WooCommerce → Status → Logs.
Order lines without a matching NetSuite item (REST mode). A line whose product cannot be matched to a NetSuite item does not block the order. The order is created from the lines that could be matched, and its entry on the Logs page names each skipped product; the entry is marked as failed even though the order was created. Until those products are linked and the order is synchronised again (Order actions → Sync to NetSuite on the order screen), the NetSuite order total will not match the WooCommerce total. An order with no matching line at all still fails.
7.1 Cash Sale configuration
↑ Back to topWhere Order record type is set to CashSale, 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 rules under Conditional mapping rules on the Export (Woo → NetSuite) 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 topThe 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 topConditional mapping assigns additional values to NetSuite records without requiring development work. It is available for both order and customer synchronisation, in the Conditional mapping rules section of:
- Sync → Orders → Export (Woo → NetSuite) for orders;
- Sync → Customers → Woo → NetSuite for customers.
Add the first rule with Add your first rule, and further rules with Add conditional rule, Always-set rule, or Copy-from-Woo rule. New rules are added at the bottom and rules cannot be reordered; Duplicate inserts a copy directly below the original. 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 value satisfies a specified condition (is, is not, contains, does not contain). The value tested may be a customer field, customer meta, an order field, or order meta. |
| 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. With Skip when updating, the NetSuite field is left out entirely when an existing record is updated, even if another rule without the option targets the same field; the rule still applies when a record is created. Select Save in the Conditional mapping rules section to store the rules.
Conditions ignore upper and lower case. With is or is not, the value null tests whether the WooCommerce value is empty or not empty. A Set when… rule with an empty value is ignored, and Copy from Woo skips empty WooCommerce values.
8.1 Selecting the correct field type
↑ Back to topSelecting 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, ordepartment. Select the field from the list; the type is determined automatically. - Custom field. A field defined within the NetSuite account, prefixed
custbody,custcol, orcustentity. 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 (1 or 0 are also accepted) |
| Date, Date/Time | Date / time | Date value |
| Date, Date/Time, to be filled with the date of synchronisation | Current date (auto) | Any value, such as today; a rule with an empty value is ignored. The date of synchronisation is sent in its place. |
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 topConfigure under Sync → Customers → Woo → NetSuite, in the Sync to NetSuite section.
| Setting | Description |
| Enable customer sync | Sends customers to NetSuite when they register through WooCommerce (at checkout or in My Account), update their profile, or are created in the WordPress admin. Accounts created on the standard WordPress registration form are sent at their first profile update or order. When order synchronisation is enabled, each order’s customer is also created or updated in NetSuite with the order, whether or not this setting is on. |
| Match existing customers by | Determines how an existing NetSuite customer is identified before a new record is created: Email, Company name, or Both. |
| Customer entity ID | NetSuite auto permits NetSuite to assign the Entity ID; Use email submits the customer’s email address (REST mode; in SOAP mode, NetSuite assigns the ID). A conditional mapping rule targeting entityId overrides both options. |
| Send customers as | Individual creates individual (person) customers. Company creates company customers; where no company name is present, the customer’s first and last name are used as the company name. Mixed (smart) creates a company customer only where the billing address includes a company name, and an individual otherwise. |
| When to send as company | Appears when Send customers as is set to Company: Always, or Only when billing has company (which behaves as Mixed (smart)). |
| Also create a contact record | Appears for Company and Mixed (smart). 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. |
| Update behaviour | Create + update refreshes existing NetSuite customers; Only create new leaves existing records unmodified. |
| Address on update | When an existing NetSuite customer is updated: Replace existing replaces the customer’s NetSuite addresses with the WooCommerce addresses; Add as new adds the WooCommerce addresses as new address entries, keeping the existing ones. |
| Sync these user roles | Restricts synchronisation to users holding a selected WordPress role. Orders placed by registered users without a selected role are not sent to NetSuite either; guest orders are unaffected. Select every role that places orders, such as Customer. Always select at least one role: with none selected, REST mode sends every user, including administrators and shop managers, while SOAP mode sends no registered customers and none of their orders. |
Customer conditional mapping rules are defined in the Conditional mapping rules section of the same tab. Refer to Section 8.
Each user’s profile in the WordPress admin shows a read-only NetSuite Internal ID. Clear NetSuite ID removes the link immediately, without confirmation; the next synchronisation matches the customer in NetSuite again.
10. Product Import
↑ Back to topProduct 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 Sync → Products, in the General section. Product Import fills in product details only: prices and stock come from inventory and price synchronisation (Section 6), and categories are not imported. Inactive NetSuite items are never imported, and products are never deleted or unpublished in WooCommerce.
| 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 | Published, Draft, Pending review, or Private. Applies to newly created products only; existing products keep their status. If no status is selected, no new products are created. |
| Item types to sync | Any combination of Inventory item, Assembly item, Kit item, Group item, and Matrix item. Kit items hold no stock of their own in NetSuite, so stock synchronisation does not apply to them. |
| Matrix items | Appears when Matrix item is selected. Determines what is imported from each matrix: Parent item only, Variations only, or Both parent and variations (variable product). |
| How often to sync | Schedule for automatic import: Hourly, Twice Daily, or Daily. |
| Run import now | Appears when Sync products from NetSuite is on. Select Import products now to queue an immediate background import using the settings on the screen. Unsaved changes are saved first. |
Matrix items. NetSuite matrix items are imported only when Matrix item is selected. With Both parent and variations in REST mode, the NetSuite parent becomes a WooCommerce variable product, its matrix options (such as Size or Colour) become product attributes, and each NetSuite variation becomes a variation of that product, with its own stock and price. Parent item only and Variations only, and all choices in SOAP mode, import them as separate simple products. Products that earlier versions imported as simple products are converted in place and keep their IDs.
Group items. A NetSuite group item becomes a WooCommerce grouped product, with the group’s member items as its linked products. Members are matched by SKU, so the member items must also exist in WooCommerce, for example by importing their item types as well. Members not yet in WooCommerce are listed in WooCommerce → Status → Logs and are linked by a later import once they exist. Kit items remain simple products, as a kit sells as a single unit at its own price.
Field mapping. In the Field mapping section, each WooCommerce product field (Title, Description, Short description, Tags, Weight, Height, Length, Width, Product image, and Product gallery) 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. New products are named after their SKU until Title is mapped with Create switched on. Images are downloaded in the background a few minutes after the import. A product that already has a featured image keeps it; the gallery is refreshed when its images change in NetSuite.
11. Customer Import
↑ Back to topCustomer Import creates and updates WordPress user accounts from NetSuite customer records using the NetSuite REST Web Services connection. No RESTlet or SuiteScript deployment is required. Configure under Sync → Customers → NetSuite → Woo, in the Customer import section. Customers are matched to existing WordPress users by email address. Any existing user with the same email address is updated, including administrators, and NetSuite customers that share an email address are merged into one user.
| Setting | Description |
| Import customers from NetSuite | Enables scheduled customer import. |
| How often to import | Schedule for automatic import: Hourly, Twice Daily, or Daily. |
| Only import modified customers | Restricts subsequent runs to customers modified since the previous import. The initial run retrieves all customers. |
| Filter by NetSuite field | Optional. Restricts import to customers where a specified NetSuite checkbox field is selected, for example custentity_sync_to_woo. Leave blank to import all customers. |
| Role for imported customers | The WordPress role assigned to newly created users. Existing users keep their role. |
| Customer types to import | Individuals, Companies, or both. Always select at least one: with neither selected, REST mode imports every customer and SOAP mode imports none. |
| Run import now | Appears when Import customers from NetSuite is on. Select Import customers now to queue an immediate background import using the saved settings. |
Field mapping. In the Field mapping section, each WordPress user field (User login, Password, First name, Last name, Email, Phone, Company, Billing address, and Shipping address) is mapped to a NetSuite field identifier, with independent Create and Update control. The billing and shipping address rows are fixed: complete addresses are imported, and only their Create and Update controls can be changed. Additional fields may be mapped using Add custom field mapping. Map the Email row (for example, to email); customers without a valid email address are skipped.
To set a password for new users, switch on Create for the Password row. The value of the mapped NetSuite field is used, or a random password is generated where no field is mapped or the field is empty. With Email the generated password to the new user also switched on, WordPress’s new-account email is sent, containing a link for the user to set their own password.
12. Refund Synchronisation
↑ Back to topConfigure under Sync → Orders → Refunds. Each direction may be enabled independently. Refunds are exchanged only for orders that have been synchronised to NetSuite.
| Setting | Behaviour |
| Pull refunds: NetSuite → WooCommerce | A Return Authorisation created in NetSuite from a synchronised order creates a corresponding WooCommerce refund, following the NetSuite sequence of Fulfil, Authorise Return, Receive, and Refund. NetSuite is checked hourly for orders in the Processing or Completed status. The refund is recorded against the WooCommerce order only; no payment is returned through the payment gateway. Only Return Authorisation lines for products linked to NetSuite items are refunded; tax and shipping are not included, and stock is not restocked. The 1,000 most recent eligible orders are checked, and fully refunded orders are no longer checked. |
| NetSuite refund status (optional) | Appears when pulling refunds is on. Restricts which Return Authorisations are brought into WooCommerce: Both (the default), PENDING BILLING (those still awaiting receipt of the returned items), or REFUNDED (those already refunded). |
| Push refunds: WooCommerce → NetSuite | A WooCommerce refund creates a corresponding NetSuite Return Authorisation while the refund is saved. The order must have a NetSuite customer recorded. A failure is logged but not retried. In SOAP mode, no amount is sent, so NetSuite may authorise the return of the whole order. |
A refund is never sent back in the direction it came from, so enabling both directions does not create duplicates.
13. Order Tracking and Fulfilment
↑ Back to topConfigure under Sync → Orders → Fulfillment. This tab is available only when Order record type is set to SalesOrder (Section 7). NetSuite is checked hourly for orders in the Processing status while any of the three settings below is switched on, and tracking details are stored whenever they are found.
| Setting | Description |
| Enable fulfillment sync | Retrieves fulfilment information, including the tracking number, from NetSuite and applies it to WooCommerce orders. |
| Auto-complete order on fulfillment | Sets the order status to Completed when NetSuite reports the order as fulfilled (REST mode) or billed (SOAP mode). This adds the order note Order fulfilled via NetSuite., sends WooCommerce’s Completed order email, and creates the invoice where the invoice status is Completed. |
| Email customer tracking | Sends the customer a tracking notification. Sent once per order. |
| Tracking number meta key | The tracking number is always stored in the order-tracking fields used by the YITH order tracking plugin. In SOAP mode, it is also stored in the order meta key entered here. |
| Shipping courier meta key | The order meta key used to store the shipping carrier. Leave blank to use the YITH order-tracking field. |
| Pickup date meta key | The order meta key used to store the ship or pickup date. Leave blank to use the YITH order-tracking field. |
Tracking email. The notification appears as NetSuite Order Tracking in WooCommerce → Settings → Emails, where its subject (default Order Tracking), heading, and email type can be changed while a fulfilment setting is switched on. It is sent once per order, when the first tracking number arrives. Themes can override the template by copying it to yourtheme/woocommerce/emails/email-netsuite-trackingno-recieved.php.
To show the tracking number to customers in My Account → Orders, switch on Display NetSuite order tracking number under Export (Woo → NetSuite) → General (Section 7).
14. Logging, Import, and Export
↑ Back to topLogs. Order, customer, inventory, price, and refund operations are recorded on the Logs page (Tools → Logs). Each entry shows its status, the operation, the WooCommerce object, the message returned by NetSuite, and the time. Use the All, Success, and Failed tabs, the search box, and Filter (to sort) to locate an entry; these apply to the page of entries currently loaded. Where an entry has request and response files, select REQ or RES to download them, which is the most direct method of establishing what was transmitted. In REST mode, each download opens with a summary: the operation, the WooCommerce order or customer ID, whether it succeeded and, where it did not, NetSuite’s exact error message. Files carry their real format: .json in REST mode and .xml in SOAP mode. Where an order or customer was sent several times, the download contains the most recent attempt. Clear all logs permanently deletes every entry.
Product import, customer import, tracking updates, refunds received from NetSuite, and the hourly order catch-up are recorded in WooCommerce → Status → Logs, under the sources tmwni-action-scheduler and netsuite-integration.
Configuration import and export. On the Import / Export page (Tools → Import / Export), configuration may be exported for backup purposes or transferred between staging and production environments. Export all settings downloads a file named netsuite-integration-settings-YYYY-MM-DD.json, containing all settings together with order and customer conditional mapping rules. To import, select or drop a previously exported .json file under Import settings, review the Confirm import dialogue, and select Apply settings. Settings missing from the file are kept, and conditional mapping rules change only if the file contains rules.
Important: Exported files can contain NetSuite credentials (in SOAP mode they always do) 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. An import cannot be undone, so export the current configuration first.
Data and privacy. In REST mode, order and customer data is sent to NetSuite through the hosted connector service. For support, the connector service can read a signed diagnostics snapshot (environment, scheduled tasks, the extension’s log entries, and the WordPress debug log); each read is recorded on the Logs page. Request and response files in wp-content/uploads/TM-NetSuite/ contain customer details and are not deleted automatically; Clear all logs removes the log entries but keeps these files.
15. Frequently Asked Questions
↑ Back to topDoes 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 WooCommerce products be sent to NetSuite? No. Products travel from NetSuite to WooCommerce only; WooCommerce products, prices, and stock levels are never created or updated in NetSuite.
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. In REST mode, the secrets are held by the connector service; in SOAP mode, they are encrypted in the WordPress database (this requires the PHP OpenSSL extension).
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. |
| Connection test reports a timeout, DNS, or SSL problem | The web server could not reach the connector service (REST mode), so the credentials were not tested. Select Copy message for your host and send the message to the hosting provider. |
| “You must enter at least one line item” | Correct the SKU mapping field (Sync → Inventory → Common settings) 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. The Logs page records the reason. |
| “Record assemblyitemlocations was not found” during inventory synchronisation | The NetSuite account does not use the Assembly Items feature. Clear Assembly item under Item types to sync on the Inventory page. |
| “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 Sync → Customers → Woo → NetSuite. |
| “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. Switch on Apply tax code to items and select a Tax code under Sync → Orders → Export (Woo → NetSuite) → 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 switch off Sync coupons as discount items. |
| “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 and, when the reply is lost, looks the order up in NetSuite and records it as synchronised. |
| 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. |
| Customer import runs but creates no users | Map the Email row in the customer import field mapping, and (in SOAP mode) select at least one of Individuals or Companies under Customer types to import (Sync → Customers → NetSuite → Woo). |
| Product import creates no products | Select a Status for new / updated products, and set the SKU mapping field (Section 6.1). |
| A synchronisation reports that it was blocked by a firewall or CDN | Allow requests to /wp-json/tmwni/ in the firewall, CDN, or security plugin, or remove the staging password. Refer to Section 1. |
| “This site cannot run background tasks” | The site cannot send requests to itself. Check Tools → Site Health in WordPress and ask the hosting provider to allow loopback requests. |
| Notice: “NetSuite Integration: not connected” | The stored credentials could not be moved to the connector service. Enter the credentials under Sync → Setup and select Test connection. |
| Orders do not reach NetSuite | Check that Auto-sync on WooCommerce status is set, that the customer’s role is selected under Sync these user roles, and that WooCommerce Scheduled Actions in the group tmwni are not overdue. Then use Resubmit on the Dashboard. |
| No invoice is created (REST mode) | Select an invoice status that comes after the auto-sync status. Refer to Section 7. |
| The Fulfillment tab shows no settings | Fulfilment synchronisation requires Order record type to be set to SalesOrder on the Export (Woo → NetSuite) tab. |
| A setting reverts after leaving the page | Each section has its own Save button. Save the section before leaving the page. |
Developed by TechMarbles. For support, use Tools → Help in the plugin.
