NetSuite REST API Integration Guide for Ecommerce Developers

Disclosure: Some links in this article are affiliate links. We may earn a commission if you purchase through them, at no extra cost to you. We only recommend solutions we've vetted through real client implementations.

If you're a developer building a custom integration with NetSuite for an ecommerce brand, you've likely discovered that NetSuite's API landscape is more complex than most platforms. There isn't one API — there are three: the legacy SOAP-based SuiteTalk API, the newer REST API, and RESTlets (custom REST endpoints you deploy within NetSuite). Each serves different purposes, has different capabilities, and comes with different limitations.

In our work building ecommerce integrations, we've seen teams waste weeks choosing the wrong API for their use case, fighting with authentication that should have been straightforward, and hitting governance limits that could have been avoided with better architecture. This guide is the resource we wish we'd had when we started — a practical, developer-focused walkthrough of NetSuite's API options, authentication setup, common ecommerce integration patterns, and the operational realities of rate limiting and error handling.

Key Takeaways

• REST API is best for standard CRUD operations on NetSuite records — orders, items, customers, inventory
• SOAP (SuiteTalk) is more mature and supports operations the REST API doesn't yet — saved searches, custom record types (in some cases), and workflow triggers
• RESTlets give you the most flexibility — custom logic deployed as scripts within NetSuite that expose REST endpoints
• Token-Based Authentication (TBA) is the only production-appropriate auth method — never use user credentials in integration code
• Governance limits will constrain your integration design — plan for them from the start, not as an afterthought

REST API vs. SOAP vs. RESTlets: When Should You Use Each?

REST API (SuiteQL)

NetSuite's REST API was introduced to modernize access to NetSuite data. It uses standard REST conventions (GET, POST, PATCH, DELETE) and returns JSON. It also supports SuiteQL — a SQL-like query language that lets you query NetSuite records with familiar SELECT syntax.

Use REST API when:

• You need standard CRUD operations on NetSuite records (create sales order, update customer, read inventory)
• You want to query data using SQL-like syntax (SuiteQL)
• Your integration is built in a modern language/framework that works well with REST/JSON
• You're building a new integration from scratch (prefer REST over SOAP for new projects)

Strengths:

• JSON request/response (no XML parsing)
• SuiteQL for complex queries
• Metadata API for discovering record types, fields, and relationships
• Better developer experience than SOAP

Limitations:

• Not all record types are supported yet (coverage is expanding but not complete)
• Some operations available in SOAP aren't available in REST (e.g., some transformation operations)
• Documentation can be incomplete for edge cases
• Batch operations are limited compared to SOAP

SOAP API (SuiteTalk)

SuiteTalk is NetSuite's original API. It's been available for 15+ years and has the broadest record type coverage and operation support. If something can be done via the NetSuite UI, it can almost certainly be done via SuiteTalk.

Use SOAP when:

• The record type you need isn't available in the REST API
• You need Saved Search execution via API (REST API uses SuiteQL instead, which covers most cases)
• You need complex record transformations (e.g., transforming a sales order into an item fulfillment)
• You're maintaining an existing SOAP-based integration

Strengths:

• Complete record type coverage
• Saved Search execution
• Record transformation support
• Extensive documentation and community resources
• Stable — API versions rarely break backward compatibility

Limitations:

• XML-based (verbose, harder to work with than JSON)
• WSDL files are enormous and can cause issues with some SOAP libraries
• Slower than REST for equivalent operations
• The future is clearly REST — SOAP will eventually be deprecated (though not anytime soon)

RESTlets

RESTlets are custom JavaScript files deployed as scripts within NetSuite that expose REST endpoints. They run on NetSuite's server and have access to NetSuite's entire SuiteScript API, which means they can do anything the NetSuite UI can do.

Use RESTlets when:

• You need custom business logic that can't be expressed through standard API operations
• You want to bundle multiple operations into a single API call (e.g., create a sales order, apply a payment, and create an item fulfillment in one request)
• You need to access NetSuite features not exposed through REST or SOAP APIs
• You want to build an endpoint that returns exactly the data your integration needs (custom response format)

Strengths:

• Complete access to SuiteScript API (unlimited flexibility)
• Custom request/response formats
• Can implement complex business logic server-side
• Reduces round trips (multiple operations per call)
• JSON request/response

Limitations:

• Requires SuiteScript development skills (JavaScript)
• Deployed as scripts within NetSuite (requires admin access and script deployment)
• Subject to SuiteScript governance limits
• Harder to maintain — code lives in NetSuite, not your codebase
• Each RESTlet has its own endpoint URL, making API management more complex

Our Recommendation for Ecommerce

For most ecommerce integration patterns:

• Primary: REST API with SuiteQL for reads and standard operations
• Supplement with RESTlets for complex operations (order creation with custom logic, bulk inventory updates)
• SOAP only when needed for record types or operations not available in REST

How Do You Set Up Token-Based Authentication?

Token-Based Authentication (TBA) is the only authentication method you should use for production integrations. OAuth 2.0 is available for some use cases, but TBA remains the standard for server-to-server integration.

Step 1: Enable TBA in NetSuite

1. Go to Setup → Company → Enable Features → SuiteCloud
2. Check Token-Based Authentication under Manage Authentication
3. Save

Step 2: Create an Integration Record

1. Go to Setup → Integration → Manage Integrations → New
2. Name it (e.g., "Ecommerce Integration")
3. Check Token-Based Authentication under Authentication
4. Uncheck TBA: Authorization Flow if you're doing machine-to-machine auth (no user interaction)
5. Save
6. Copy the Consumer Key and Consumer Secret immediately — the Consumer Secret is shown only once

Step 3: Create an Access Token

1. Go to Setup → Users/Roles → Access Tokens → New
2. Select the Application (Integration Record) you created
3. Select the User who will own this token
4. Select the Role that defines permissions
5. Save
6. Copy the Token ID and Token Secret immediately — the Token Secret is shown only once

Step 4: Build the OAuth 1.0 Signature

TBA uses OAuth 1.0 signatures. Each API request must include an Authorization header with:

OAuth realm="ACCOUNT_ID",
oauth_consumer_key="CONSUMER_KEY",
oauth_token="TOKEN_ID",
oauth_nonce="RANDOM_STRING",
oauth_timestamp="UNIX_TIMESTAMP",
oauth_signature_method="HMAC-SHA256",
oauth_version="1.0",
oauth_signature="COMPUTED_SIGNATURE"

The signature is computed by:

1. Building a base string from the HTTP method, URL, and sorted parameters
2. Creating a signing key from CONSUMER_SECRET&TOKEN_SECRET
3. Computing HMAC-SHA256 of the base string with the signing key
4. Base64-encoding the result

Most HTTP libraries have OAuth 1.0 support built in. In Node.js, use the oauth-1.0a package. In Python, use requests-oauthlib. Don't implement the signature algorithm manually unless you enjoy debugging subtle encoding issues.

Step 5: Test the Connection

Make a simple GET request to verify authentication works:

GET https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/record/v1/customer/123
Authorization: OAuth realm="ACCOUNT_ID", ...

If you get a 200 response with customer data, your authentication is working.

Common Authentication Errors

Error	Cause	Fix
401 Invalid login	Wrong consumer key, token, or signature	Double-check all four credentials; verify signature computation
403 Insufficient permissions	The role assigned to the token doesn't have access to the record type	Add permissions to the role
INVALID_LOGIN_ATTEMPT	Account ID is wrong, or TBA isn't enabled	Verify account ID format (numbers, not subdomain)
SSS_REQUEST_LIMIT_EXCEEDED	Governance limit hit	Back off and retry; see rate limiting section

What Are the Common API Patterns for Ecommerce?

Pattern 1: Order Sync (Ecommerce Platform → NetSuite)

The most common ecommerce integration pattern. New orders from Shopify, BigCommerce, WooCommerce, or a custom storefront need to create sales orders in NetSuite.

REST API approach:

POST /services/rest/record/v1/salesOrder
Content-Type: application/json

{
  "entity": {"id": "12345"},
  "tranDate": "2026-03-22",
  "item": {
    "items": [
      {
        "item": {"id": "67890"},
        "quantity": 2,
        "rate": 49.99
      }
    ]
  },
  "shippingAddress": {
    "addressee": "John Smith",
    "addr1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": {"id": "US"}
  }
}

Key considerations:

• Idempotency: Use externalId to prevent duplicate orders. Set the external ID to the order ID from your ecommerce platform. If you POST the same external ID twice, NetSuite rejects the duplicate.
• Customer lookup: Before creating the order, look up the customer by email. If they don't exist, create them first (or use a RESTlet that handles customer creation and order creation atomically).
• Error handling: If the order creation fails (invalid item, pricing issue, required field missing), your integration must capture the error, log it, and either retry or queue for manual review.

Pattern 2: Inventory Sync (NetSuite → Ecommerce Platform)

Push available inventory from NetSuite to your ecommerce platform.

SuiteQL approach:

POST /services/rest/query/v1/suiteql
Content-Type: application/json

{
  "q": "SELECT item.itemid, item.id, inventoryBalance.quantityavailable, inventoryBalance.quantityonhand, inventoryBalance.location FROM item INNER JOIN inventoryBalance ON item.id = inventoryBalance.item WHERE item.isinactive = 'F' AND inventoryBalance.quantityavailable > 0"
}

Key considerations:

• Polling vs. push: The REST API doesn't support webhooks. You must poll NetSuite for inventory changes. Use a SuiteQL query filtered by last-modified date to pull only changed records.
• Multi-location: If you have multiple warehouses, decide whether to push aggregate inventory or per-location inventory to your ecommerce platform.
• Frequency: Poll every 5–15 minutes for high-velocity SKUs. Use a saved search with a "last modified" filter to minimize data transfer.

Pattern 3: Customer Sync (Bidirectional)

New customers from ecommerce create customer records in NetSuite. Customer updates in NetSuite (price level, credit terms) push to ecommerce.

REST API — Create Customer:

POST /services/rest/record/v1/customer
Content-Type: application/json

{
  "companyName": "Acme Corp",
  "email": "buyer@acme.com",
  "isPerson": false,
  "subsidiary": {"id": "1"},
  "priceLevel": {"id": "3"},
  "addressBook": {
    "items": [
      {
        "defaultBilling": true,
        "addressBookAddress": {
          "addr1": "456 Oak Ave",
          "city": "Denver",
          "state": "CO",
          "zip": "80202",
          "country": {"id": "US"}
        }
      }
    ]
  }
}

Pattern 4: Fulfillment Update (NetSuite → Ecommerce Platform)

When an order is fulfilled in NetSuite, push the tracking number and carrier to your ecommerce platform.

SuiteQL — Query Recent Fulfillments:

POST /services/rest/query/v1/suiteql

{
  "q": "SELECT tranid, linkedTrackingNumbers, shipMethod, createdDate FROM itemFulfillment WHERE createdDate > TO_DATE('2026-03-22', 'YYYY-MM-DD') ORDER BY createdDate DESC"
}

Use the linked tracking numbers and ship method to update the corresponding order on your ecommerce platform.

How Do You Handle Rate Limiting and Governance?

This is where many custom integrations hit a wall. NetSuite enforces strict governance limits that constrain how much work your integration can do.

REST API Concurrency Limits

NetSuite limits the number of concurrent REST API requests per account. The exact limit depends on your NetSuite license tier:

• Standard: 5 concurrent requests
• Premium: 10 concurrent requests
• Higher tiers: Up to 25+ concurrent requests

If you exceed the concurrency limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff: wait 1 second, then 2 seconds, then 4 seconds, then 8 seconds before retrying.

SuiteScript Governance (for RESTlets)

RESTlets run as SuiteScript and are subject to governance unit limits:

Operation	Governance Units
Record load	5–10 units
Record save	10–20 units
Search execution	10 units
HTTP request (outbound)	10 units
RESTlet limit per execution	5,000 units

This means a single RESTlet execution can perform roughly 250–500 record operations before hitting the limit. For bulk operations (syncing 1,000 inventory items), you need to paginate across multiple RESTlet calls.

Strategies for Staying Within Limits

1. Batch operations: Instead of creating orders one at a time, batch them in groups of 10–25 and process them in a single RESTlet call.
2. Differential sync: Only sync records that have changed since the last sync. Use timestamps or record internal IDs to track what's been processed.
3. Off-peak scheduling: Run heavy sync operations during off-peak hours (nights, weekends) when the concurrency limits are less likely to be contested by other integrations or users.
4. Queue and throttle: Implement a queue in your middleware that processes records at a controlled rate, never exceeding the concurrency limit.
5. Cache aggressively: Cache reference data (item records, customer records) that doesn't change frequently. Don't re-query NetSuite for data you already have.

Monitoring API Usage

Use NetSuite's Application Performance Management (APM) to monitor your integration's API usage:

1. Go to Setup → SuiteCloud → SuiteCloud Usage Audit Log
2. Filter by Integration Record to see your integration's API calls
3. Monitor for spikes, errors, and governance limit violations

How Do You Handle Errors Gracefully?

Error Response Patterns

NetSuite REST API errors return JSON with error codes and messages:

{
  "type": "error.SuiteScriptError",
  "title": "Invalid field value",
  "status": 400,
  "detail": "Invalid reference key 99999 for field entity",
  "o:errorCode": "INVALID_FLD_VALUE"
}

Error Handling Strategy

1. Categorize errors:

   • Retryable: Rate limit (429), server error (500, 503), timeout. Retry with exponential backoff.
   • Non-retryable: Bad request (400), not found (404), permission denied (403). Log the error, queue for manual review, and don't retry automatically.
   • Partial success: Some operations succeed while others fail. Track which records succeeded and retry only the failures.

2. Dead letter queue: Records that fail after multiple retries go into a dead letter queue. Alert your team to review and resolve manually. Never drop failed records silently.

3. Logging: Log every API request and response (with sensitive data redacted). When something fails at 2 AM, you'll need the logs to debug it. Include the request timestamp, endpoint, request body, response code, response body, and duration.

4. Alerting: Set up alerts for:

   • Error rate exceeding threshold (e.g., more than 5% of requests failing)
   • Queue depth exceeding threshold (e.g., more than 100 unprocessed records)
   • Sync latency exceeding threshold (e.g., orders not synced within 30 minutes)

Frequently Asked Questions

Can I use OAuth 2.0 instead of TBA?

NetSuite supports OAuth 2.0 for user-authenticated flows (where a user logs in and grants access). For machine-to-machine integration (no user interaction), TBA is still the standard. If you're building a SuiteApp that end users install, OAuth 2.0 makes sense. For a backend integration, use TBA.

How do I find the internal ID for a record type or field?

Use the REST API's metadata endpoints: GET /services/rest/record/v1/metadata-catalog/ returns all available record types. GET /services/rest/record/v1/metadata-catalog/salesOrder returns all fields for sales orders, including internal IDs, field types, and relationships.

Can I use the REST API from a browser (client-side JavaScript)?

Not recommended for production. TBA credentials would be exposed in the browser, which is a security risk. Use the REST API from server-side code only. If you need client-side access to NetSuite data, build a backend API that proxies requests to NetSuite.

How do I handle NetSuite sandbox vs. production?

NetSuite provides sandbox accounts for testing. Use a separate set of TBA credentials for sandbox. The REST API base URL differs — sandbox uses {ACCOUNT_ID}.suitetalk.api.netsuite.com with the sandbox account ID. Keep your integration configuration environment-aware so you can switch between sandbox and production without code changes.

Is there a GraphQL API for NetSuite?

No. NetSuite does not offer a GraphQL API. SuiteQL (available through the REST API) provides SQL-like query capabilities that serve a similar purpose for flexible data retrieval.

What Should You Do Next?

Building a custom NetSuite integration is a significant engineering effort, but it gives you complete control over your data flows, business logic, and system behavior. The key is choosing the right API for each use case, implementing authentication correctly, respecting governance limits, and building robust error handling from day one.

Start with a proof of concept: set up TBA authentication, make a few REST API calls to read and write records, and test SuiteQL queries against your data. This will give you a feel for the API's capabilities and limitations before you commit to a full integration build.

Take our free integration assessment to evaluate your custom integration requirements, understand the API approach best suited to your ecommerce architecture, and get guidance on implementation patterns and estimated development effort.