Skip to main content

NetSuite

Oracle NetSuite is a cloud-based ERP (Enterprise Resource Planning) platform that combines accounting, financials, CRM, inventory and order management, procurement, and HR/payroll into a single suite. NetSuite is used by tens of thousands of businesses worldwide to run core operations — invoicing, customer and vendor management, sales orders, purchase orders, journal entries, inventory tracking, and consolidated financial reporting (including OneWorld multi-subsidiary).

The Webrix NetSuite connector talks to NetSuite's REST Web Services and SuiteQL endpoints over OAuth 2.0, giving you secure, per-user access to records (customers, vendors, items, transactions) and SQL-like analytics across your account.

Authentication Types​

NetSuite supports 1 authentication method through this connector:

  • OAuth 2.0 (Authorization Code Grant) — Create your own integration record in NetSuite and connect each user with their NetSuite account.
    • Pros: Secure, per-user authentication, automatic token refresh, supports all REST Web Services scopes, recommended by Oracle for new integrations.
    • Cons: Requires administrator access in NetSuite to create the integration record and enable REST Web Services + OAuth 2.0 features.
    • Best for: Production deployments where each user authenticates with their own NetSuite credentials and permissions.
tip

NetSuite also supports Token-Based Authentication (TBA) via OAuth 1.0a and Client Credentials (M2M) flows. The Webrix connector uses OAuth 2.0 Authorization Code because it provides per-user attribution and the cleanest UX for end users.

General Settings​

Before connecting, you must provide:

  • NetSuite Account ID — Your NetSuite account identifier in URL form (lowercase, with hyphens instead of underscores).
    • Production example: 1234567
    • Sandbox example: 1234567-sb1
    • Release Preview example: 1234567-rp1

Where to find your Account ID​

  1. Log in to NetSuite as an administrator
  2. Go to Setup → Company → Company Information
  3. Look for the Account ID field

NetSuite displays the account ID in two forms:

  • Internal form (with underscores, e.g. 1234567_SB1) — used in some UI screens
  • URL form (lowercase with hyphens, e.g. 1234567-sb1) — used in API endpoints

The Webrix connector requires the URL form. You can also see it in the URL when you're logged in to NetSuite — the subdomain of the URL is your account ID in URL form.

Setting up OAuth​

To use NetSuite with Webrix, you need to enable REST Web Services + OAuth 2.0 in your NetSuite account, then create an integration record to obtain a Client ID and Client Secret.

1. Enable REST Web Services and OAuth 2.0​

  1. Log in to NetSuite as an administrator

  2. Go to Setup → Company → Enable Features

  3. Click the SuiteCloud tab

  4. Under the SuiteTalk (Web Services) section, enable:

    • REST Web Services

  5. Under the Manage Authentication section, enable:

    • OAuth 2.0

  6. Click Save

    tip

    If you don't see these options, ensure your role has the Setup permission. The Administrator role has it by default.

2. Create an Integration Record​

  1. Go to Setup → Integration → Manage Integrations → New

  2. Fill in the Name (e.g., "Webrix MCP Integration")

  3. Set the State to Enabled

  4. Under Authentication:

    • Uncheck Token-Based Authentication
    • Check Authorization Code Grant (under OAuth 2.0)

  5. Under Scopes, select the scopes you need:

    • REST Web Services — required for record API and SuiteQL (most common)
    • RESTlets — only needed if you'll call custom RESTlet scripts
    • SuiteAnalytics Connect — only needed for SuiteAnalytics Connect access

  6. Copy the Redirect URI from Webrix and paste it into the Redirect URI field

    tip

    You can find the Redirect URI in Webrix when configuring the NetSuite connector in the Setup tab → Authentication section.

  7. Click Save

  8. NetSuite displays the Client Credentials at the bottom of the screen — copy:

    • Client ID (Consumer Key)
    • Client Secret (Consumer Secret)
    warning

    The Client Secret is shown only once. Copy it immediately and store it securely. If you lose it, you must reset the credentials and update Webrix.

3. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select NetSuite and click Use

  3. Under Authentication Type, select OAuth

  4. Paste your Client ID and Client Secret into the corresponding fields

  5. Under Scopes, click Add and select:

    • rest_webservices — required for all record and SuiteQL operations
    • restlets — optional, only if you call RESTlets
    • suite_analytics — optional, for SuiteAnalytics Connect

    Minimum required: rest_webservices

  6. Under Configuration, set the NetSuite Account ID in URL form (e.g. 1234567 or 1234567-sb1)

  7. Click Save Changes

4. Test the Connection​

  1. After saving, click Connect to test the OAuth flow

  2. You'll be redirected to NetSuite's authorization page

  3. Sign in to your NetSuite account (if not already signed in)

  4. Select the Role to use for the integration (use a role with the permissions your tools need)

  5. Review the requested permissions and click Allow

  6. You'll be redirected back to Webrix with a successful connection

Understanding the Record API and SuiteQL​

The connector uses two NetSuite endpoints:

Record API (/services/rest/record/v1/)​

Used for typed CRUD operations on individual record types:

  • GET /record/v1/customer — list customers
  • GET /record/v1/customer/{id} — get a customer
  • POST /record/v1/customer — create a customer
  • PATCH /record/v1/customer/{id} — update a customer (sparse update)
  • DELETE /record/v1/customer/{id} — delete a customer

Tools like List Customers, Get Sales Order, and Create Purchase Order use this API. For record types not exposed by a dedicated tool, use List Records, Get Record, and Delete Record with the camelCase recordType (e.g., opportunity, vendorBill, creditMemo, cashSale).

SuiteQL (/services/rest/query/v1/suiteql)​

Used for SQL-like analytics queries that span multiple records, perform aggregations, or filter on fields not supported by the Record API:

SELECT
  c.id,
  c.companyname,
  SUM(t.foreigntotal) AS lifetime_value
FROM customer c
LEFT JOIN transaction t ON t.entity = c.id
WHERE c.isinactive = 'F'
GROUP BY c.id, c.companyname
ORDER BY lifetime_value DESC
FETCH NEXT 50 ROWS ONLY

Use Run SuiteQL Query for these workflows.

Common Use Cases​

Customer onboarding workflow​

  1. Use List Subsidiaries to find the subsidiary internal ID (OneWorld accounts)
  2. Use Create Customer with companyName, email, and subsidiary_id
  3. Optionally use Update Customer with custom_fields to set additional fields like sales rep or category

Sales order to invoice workflow​

  1. Use List Customers (or query) to find the customer's internal ID
  2. Use List Items to find item internal IDs
  3. Use Create Sales Order with entity_id, item_lines, and subsidiary_id
  4. Once fulfilled in NetSuite, use List Invoices with q="createdfrom.id IS '<sales_order_id>'" to find the resulting invoice

Procurement workflow​

  1. Use List Vendors to find vendors
  2. Use List Items to find items to purchase
  3. Use Create Purchase Order with entity_id (vendor), item_lines, and subsidiary_id
  4. Use List Records with recordType="vendorBill" to track resulting bills

Financial reporting via SuiteQL​

  1. Use Run SuiteQL Query to pull cross-record reports — e.g., revenue by customer, AR aging, expense by department
  2. Combine with List Accounts to discover account internal IDs for filters

Bulk discovery​

  1. Use List Records with the desired recordType (e.g. cashSale, creditMemo, transferOrder) and q filter
  2. Use Get Record to fetch full details for individual records
  3. Use Run SuiteQL Query for aggregations across many records

Rate Limits​

NetSuite enforces concurrency limits per account based on your service tier:

  • Standard accounts: typically 5 concurrent requests per account
  • Premium accounts: typically 10–40 concurrent requests per account
  • SuiteCloud Plus license: increases concurrency further

NetSuite does not enforce a strict per-minute request quota, but exceeding the concurrency limit returns HTTP 429 Too Many Requests.

Best Practices:

  • Implement exponential backoff for 429 responses
  • Use SuiteQL with aggregations instead of looping over many record API calls
  • Cache reference data (subsidiaries, accounts, items) that change infrequently
  • Use limit and offset for pagination instead of fetching everything at once

Troubleshooting​

"Invalid login attempt" or 401 Unauthorized after connecting​

Cause: OAuth 2.0 is not enabled on the integration record, or the Authorization Code Grant flow is unchecked.

Solution:

  1. In NetSuite, go to Setup → Integration → Manage Integrations and open your integration record
  2. Verify OAuth 2.0 → Authorization Code Grant is checked
  3. Verify the State is Enabled
  4. Verify your role has the REST Web Services permission (Setup → Users/Roles → Manage Roles)
  5. Disconnect and reconnect in Webrix to obtain new tokens

"Invalid redirect_uri" during OAuth​

Cause: The redirect URI in the NetSuite integration record doesn't match the one Webrix is sending.

Solution:

  1. Copy the exact Redirect URI from Webrix (including https:// and any path)
  2. In NetSuite, edit the integration record and paste the URI exactly into the Redirect URI field (trailing slashes matter)
  3. Save and try connecting again

"Invalid Account ID" or DNS resolution errors​

Cause: The Account ID is in the wrong format. NetSuite requires the URL form (lowercase, hyphens) for API hostnames.

Solution:

  1. In Webrix, go to the NetSuite integration → Configuration
  2. Verify the NetSuite Account ID is in URL form:
    • ✅ 1234567 (production)
    • ✅ 1234567-sb1 (sandbox)
    • ❌ 1234567_SB1 (this is the internal form — won't work in URLs)
  3. The format must be lowercase with hyphens

403 Forbidden when calling a tool​

Cause: The user's NetSuite role lacks permission for the record type, or the integration record doesn't have the required scope.

Solution:

  1. Verify the integration record has the REST Web Services scope checked
  2. Verify the user's role has permission for the record type (e.g., Lists → Customers for customer endpoints)
  3. For SuiteQL, verify the role has SuiteAnalytics Workbook or SuiteQL permission
  4. Disconnect and reconnect to refresh the token after permission changes

"Invalid record type" error​

Cause: The recordType parameter passed to Get Record / List Records / Delete Record isn't a valid NetSuite REST record type name.

Solution:

  1. NetSuite REST record type names are camelCase, not the UI label (e.g., salesOrder, not Sales Order)
  2. Common record types: customer, contact, vendor, employee, salesOrder, invoice, purchaseOrder, vendorBill, cashSale, creditMemo, estimate, opportunity, journalEntry, inventoryItem, serviceItem, nonInventoryItem, account, subsidiary, location, classification, department, currency, task, phoneCall, message, note
  3. Refer to the NetSuite REST API Browser for the full list

SuiteQL: "User Error" or syntax errors​

Cause: SuiteQL uses Oracle SQL syntax with NetSuite-specific table and column names.

Solution:

  1. Use lowercase column and table names: SELECT id FROM customer, not SELECT ID FROM Customer
  2. Use Oracle pagination: FETCH NEXT 100 ROWS ONLY (or OFFSET 100 ROWS FETCH NEXT 100 ROWS ONLY)
  3. Boolean fields use 'T' and 'F' strings: WHERE isinactive = 'F'
  4. Date functions: TO_DATE('2024-01-01', 'YYYY-MM-DD')
  5. Test queries first in NetSuite's Analytics → SuiteQL workbench

Subsidiary required error when creating records​

Cause: OneWorld accounts require subsidiary on most records (customers, vendors, transactions).

Solution:

  1. Use List Subsidiaries to find the subsidiary internal ID
  2. Pass it as subsidiary_id when calling Create Customer / Create Sales Order / Create Purchase Order / Create Journal Entry
  3. The subsidiary must be one your role has access to

Token Refresh Failures​

Cause: Refresh tokens expire after 7 days of inactivity or 180 days total (whichever comes first), per NetSuite OAuth 2.0 policy.

Solution:

  1. Disconnect and reconnect the integration in Webrix to obtain new tokens
  2. Verify the integration record in NetSuite is still Enabled
  3. Verify the Client ID/Client Secret have not been reset

"Stale" or concurrent update errors​

Cause: Another user or process modified the record between your read and write.

Solution:

  1. Re-fetch the record with Get Customer / Get Sales Order / etc.
  2. Re-apply your update with the latest data
  3. NetSuite uses optimistic locking on most record types

Additional Resources​

Need Help?​

If you encounter issues not covered in this guide, please contact Webrix support with:

  • The exact error message
  • The tool you were using (e.g., Create Sales Order)
  • Your NetSuite account type (production / sandbox / OneWorld)
  • The HTTP status code returned (if visible)