NetSuite SuiteTalk SOAP API Capabilities

TL;DR

• Bottom line: SuiteTalk SOAP is NetSuite's legacy integration surface offering search, CRUD, and list operations via XML/HTTPS. It remains functional but is on a hard deprecation path — 2025.2 is the final SOAP endpoint, no new integrations after 2027.1, full shutdown at 2028.2. Migrate to REST. [src1, src4]
• Key limit: Search results capped at 1,000 records per page (sync); use searchMoreWithId for pagination. Write operations limited to 100-200 records per batch call depending on operation type. [src2]
• Watch out for: Concurrency is shared across SOAP, REST, and RESTlet calls in a single pool — a runaway SOAP integration can starve your REST API and RESTlet traffic. [src3, src6]
• Best for: Maintaining existing SOAP-based integrations that cannot be immediately migrated, or ESB platforms with mature SOAP stacks (MuleSoft, BizTalk, SAP PI/PO). [src1]
• Authentication: Token-Based Authentication (TBA) based on OAuth 1.0 — OAuth 2.0 is NOT supported for SOAP web services. [src5]

System Profile

This card covers Oracle NetSuite SuiteTalk SOAP Web Services, the original programmatic API for NetSuite. SuiteTalk uses document-style SOAP over HTTPS with XML serialization. It supports all major NetSuite record types (customers, transactions, items, custom records) and provides search, CRUD, and bulk list operations. The WSDL is versioned in lockstep with NetSuite releases (e.g., 2025.2 corresponds to WSDL 2025_2). All NetSuite editions (Standard, Premium, Enterprise, Ultimate) support SOAP web services, but concurrency limits vary dramatically by tier and SuiteCloud Plus licensing. [src1, src3]

Critical deprecation notice: Oracle has announced that SOAP web services will be fully removed in the 2028.2 release. The 2025.2 WSDL is the last planned SOAP endpoint. Starting with 2027.1, no new SOAP integrations can be created. All existing SOAP integrations must migrate to REST web services with OAuth 2.0 before 2028.2. [src4]

API Surfaces & Capabilities

NetSuite offers multiple API surfaces. This card focuses on SuiteTalk SOAP, but understanding where it fits relative to alternatives is critical for integration architecture decisions. [src1, src4]

Rate Limits & Quotas

Per-Request Limits

NetSuite governs SOAP web services through record limiting and request limiting. These are hard caps — exceeding them raises SOAP faults. [src2]

Concurrency Limits (Rolling)

Concurrency is the number of simultaneous API requests NetSuite will process for your account. This pool is shared across all SOAP, REST, and RESTlet requests. [src3, src6, src7]

Formula: Total concurrency = Base tier limit + (10 x number of SuiteCloud Plus licenses).

Governance Error Faults

Authentication

SuiteTalk SOAP uses Token-Based Authentication (TBA), which is based on OAuth 1.0. OAuth 2.0 is explicitly NOT supported for SOAP web services. [src5]

Authentication Gotchas

• TBA tokens are permanent and do not expire, but they can be revoked by an administrator at any time. Build your integration to handle sudden auth failures gracefully. [src5]
• TBA requires a signed OAuth 1.0 header with consumer key, consumer secret, token ID, and token secret. The signature method is HMAC-SHA256. Getting the signature base string wrong is the #1 cause of auth failures. [src5]
• Each integration record must have TBA enabled explicitly (Setup > Integration > Manage Integrations). Forgetting this step causes INVALID_LOGIN_ATTEMPT errors. [src5]
• OAuth 2.0 cannot be used for SOAP — if you see OAuth 2.0 examples in NetSuite docs, they apply to REST only. [src5, src4]
• Starting with 2027.1, no new integrations using TBA can be created for any API surface. Existing TBA integrations continue working. [src4]

Constraints

• SOAP sunset timeline: 2025.2 is the last SOAP endpoint. 2027.1 blocks new SOAP integrations. 2028.2 removes SOAP entirely. Any new integration should use REST. [src4]
• No OAuth 2.0 for SOAP: SOAP only supports TBA (OAuth 1.0). OAuth 2.0 is REST-only. [src5]
• Shared concurrency pool: SOAP, REST, and RESTlet requests share the same concurrency limit. A SOAP-heavy integration directly reduces capacity for other API surfaces. [src3]
• Record limits are per-call, not per-record: updateList at 100 records max means you need 10 calls to update 1,000 records, each consuming a concurrent slot. [src2]
• Sandbox concurrency fixed at 5: Regardless of production tier or SC+ licenses, sandbox/developer accounts are capped at 5. [src6, src7]
• No webhook/push mechanism: SOAP is pull-only. For real-time notifications, use SuiteScript User Event Scripts or RESTlets. [src1]
• WSDL backward compatibility: You can use an older WSDL against a newer NetSuite release, but NOT a newer WSDL against an older release. [src1]
• Async operations have different limits: Async variants have higher record limits (2x sync) but require polling for completion status. [src2]

Integration Pattern Decision Tree

START -- User needs to integrate with NetSuite via SOAP
|-- Is this a NEW integration (2026+)?
|   |-- YES --> STOP. Use REST API with OAuth 2.0 instead (SOAP deprecated)
|   +-- NO --> Continue (maintaining existing SOAP integration)
|
|-- What is the integration pattern?
|   |-- Real-time individual record operations
|   |   |-- Single record? --> use get/add/update/upsert/delete
|   |   +-- Multiple records (< 200)? --> use addList/updateList/upsertList
|   |
|   |-- Search/query operations
|   |   |-- Simple lookup by internal ID? --> use get or getList (up to 1,000)
|   |   |-- Complex criteria search? --> use search with SearchPreferences
|   |   |   |-- Expect < 1,000 results? --> single search call
|   |   |   +-- Expect > 1,000 results? --> search + searchMoreWithId pagination
|   |   +-- Need to reuse existing saved search? --> use search with savedSearchId
|   |
|   |-- Batch/bulk processing
|   |   |-- < 10,000 records? --> Loop with list operations + rate control
|   |   |-- < 100,000 records? --> Async operations + parallel execution
|   |   +-- > 100,000 records? --> CSV Import (not SOAP) or SuiteQL for reads
|   |
|   +-- Event-driven (real-time notifications)
|       +-- SOAP cannot push events. Use SuiteScript User Event Scripts + RESTlets
|
+-- What is the error tolerance?
    |-- Zero-loss required --> Implement idempotent upsert + external tracking table
    +-- Best-effort --> Fire-and-forget with retry on ExceededRequestLimitFault

Quick Reference

Core SOAP Operations

Step-by-Step Integration Guide

1. Set up TBA credentials in NetSuite

Navigate to Setup > Integration > Manage Integrations > New. Enable Token-Based Authentication. Note the Consumer Key and Consumer Secret. Then create a token: Setup > Users/Roles > Access Tokens > New. Select the integration, user, and role. Note the Token ID and Token Secret. [src5]

Consumer Key:    abc123...
Consumer Secret: def456...
Token ID:        ghi789...
Token Secret:    jkl012...

Verify: Go to Setup > Integration > Integration Governance. Your integration should appear with its concurrency allocation.

2. Construct the SOAP request with TBA header

Build an OAuth 1.0-signed SOAP request. The signature base string must include the account ID, consumer key, token, nonce, and timestamp. [src5]

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ns="urn:messages_2025_2.platform.webservices.netsuite.com"
               xmlns:core="urn:core_2025_2.platform.webservices.netsuite.com">
  <soap:Header>
    <ns:tokenPassport>
      <core:account>YOUR_ACCOUNT_ID</core:account>
      <core:consumerKey>YOUR_CONSUMER_KEY</core:consumerKey>
      <core:token>YOUR_TOKEN_ID</core:token>
      <core:nonce>RANDOM_NONCE</core:nonce>
      <core:timestamp>UNIX_TIMESTAMP</core:timestamp>
      <core:signature algorithm="HMAC-SHA256">COMPUTED_SIGNATURE</core:signature>
    </ns:tokenPassport>
    <ns:searchPreferences>
      <ns:pageSize>1000</ns:pageSize>
      <ns:bodyFieldsOnly>false</ns:bodyFieldsOnly>
    </ns:searchPreferences>
  </soap:Header>
  <soap:Body>
    <!-- Operation goes here -->
  </soap:Body>
</soap:Envelope>

Verify: Send a simple getServerTime call. Expected response: <getServerTimeResponse> with a timestamp.

3. Execute a search with pagination

Use search for the first page, then searchMoreWithId for subsequent pages. Each page returns up to 1,000 records (sync). [src2, src8]

<!-- Initial search -->
<soap:Body>
  <ns:search>
    <ns:searchRecord xsi:type="listRel:CustomerSearchBasic">
      <listRel:lastModifiedDate operator="after">
        <core:searchValue>2026-01-01T00:00:00Z</core:searchValue>
      </listRel:lastModifiedDate>
    </ns:searchRecord>
  </ns:search>
</soap:Body>

<!-- For page 2+: -->
<soap:Body>
  <ns:searchMoreWithId>
    <ns:searchId>WEBSERVICES_TSTDRV1234567_01012026...</ns:searchId>
    <ns:pageIndex>2</ns:pageIndex>
  </ns:searchMoreWithId>
</soap:Body>

Verify: Check <totalRecords> and <totalPages> in response. Page through all pages until pageIndex == totalPages.

4. Implement error handling and retry logic

Handle the three governance fault types and implement exponential backoff for concurrency limits. [src2, src3]

import time, random

MAX_RETRIES = 5
BASE_DELAY = 2  # seconds

def call_with_retry(soap_client, operation, *args):
    for attempt in range(MAX_RETRIES):
        try:
            return operation(*args)
        except ExceededRequestLimitFault:
            delay = BASE_DELAY * (2 ** attempt) + random.uniform(0, 1)
            print(f"Concurrency limit hit, retry {attempt+1}/{MAX_RETRIES} in {delay:.1f}s")
            time.sleep(delay)
        except ExceededRecordCountFault:
            raise ValueError("Reduce batch size below operation limit")
        except ExceededRequestSizeFault:
            raise ValueError("Request exceeds 100MB - split into smaller requests")
    raise RuntimeError(f"Failed after {MAX_RETRIES} retries")

Code Examples

Python: Search all customers modified since a date with pagination

# Input:  NetSuite account with TBA credentials, target date
# Output: All customer records modified after the given date

# pip install zeep==4.2.1
from zeep import Client
import hashlib, hmac, time, secrets, base64

WSDL_URL = "https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/wsdl/v2025_2_0/netsuite.wsdl"

def search_all_customers(client, since_date):
    search_prefs = client.get_type("ns0:SearchPreferences")(
        pageSize=1000, bodyFieldsOnly=False
    )
    search_record = {
        "basic": {
            "lastModifiedDate": {
                "operator": "after",
                "searchValue": since_date
            }
        }
    }
    result = client.service.search(searchRecord=search_record,
        _soapheaders={"tokenPassport": generate_tba_header(client),
                      "searchPreferences": search_prefs})
    all_records = list(result.searchResult.recordList.record)
    total_pages = result.searchResult.totalPages
    search_id = result.searchResult.searchId
    for page in range(2, total_pages + 1):
        page_result = client.service.searchMoreWithId(
            searchId=search_id, pageIndex=page,
            _soapheaders={"tokenPassport": generate_tba_header(client)})
        all_records.extend(page_result.searchResult.recordList.record)
        time.sleep(0.5)  # Respect concurrency pool
    return all_records

JavaScript/Node.js: Upsert records with batch splitting

// Input:  Array of record objects to upsert
// Output: Results with success/failure per record

// npm install [email protected]
const soap = require('soap');
const BATCH_SIZE = 100; // upsertList max is 100 sync

async function upsertInBatches(client, records) {
  const results = [];
  for (let i = 0; i < records.length; i += BATCH_SIZE) {
    const batch = records.slice(i, i + BATCH_SIZE);
    try {
      const response = await client.upsertListAsync({ record: batch });
      const writeResponse = response[0].writeResponseList.writeResponse;
      writeResponse.forEach((wr, idx) => {
        results.push({
          index: i + idx,
          success: wr.status.isSuccess,
          internalId: wr.baseRef?.internalId || null,
          error: wr.status.statusDetail?.[0]?.message || null
        });
      });
    } catch (err) {
      if (err.root?.Envelope?.Body?.Fault?.faultstring?.includes('ExceededRequestLimitFault')) {
        await new Promise(r => setTimeout(r, 5000));
        i -= BATCH_SIZE; // Retry this batch
      } else { throw err; }
    }
    await new Promise(r => setTimeout(r, 1000));
  }
  return results;
}

cURL: Test TBA authentication

# Input:  TBA credentials (consumer key/secret, token ID/secret, account ID)
# Output: Server time response confirming auth works

curl -X POST \
  "https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/NetSuitePort_2025_2" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPAction: "getServerTime"' \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns="urn:messages_2025_2.platform.webservices.netsuite.com"
  xmlns:core="urn:core_2025_2.platform.webservices.netsuite.com">
  <soap:Header>
    <ns:tokenPassport>
      <core:account>ACCOUNT_ID</core:account>
      <core:consumerKey>CONSUMER_KEY</core:consumerKey>
      <core:token>TOKEN_ID</core:token>
      <core:nonce>RANDOM_32_CHAR_NONCE</core:nonce>
      <core:timestamp>UNIX_TIMESTAMP</core:timestamp>
      <core:signature algorithm="HMAC-SHA256">BASE64_SIGNATURE</core:signature>
    </ns:tokenPassport>
  </soap:Header>
  <soap:Body><ns:getServerTime/></soap:Body>
</soap:Envelope>'

# Expected: <getServerTimeResponse> with <serverTime>2026-03-01T12:00:00.000Z</serverTime>

Data Mapping

Key Record Type Internal Names

Data Type Gotchas

• NetSuite datetime fields use Pacific Time (PT) by default unless the user's timezone preference is set differently. Always convert to UTC before comparing with external systems. [src8]
• Currency amounts are stored as decimals with the currency's precision. Multi-currency transactions require specifying the currency field. [src1]
• Boolean fields in SOAP use true/false strings, not 1/0. Sending 1 may cause silent data corruption. [src1]
• Custom fields use the customFieldList element with internalId matching the custom field's script ID. Wrong internal IDs are silently ignored. [src1]
• External IDs (externalId) are case-sensitive and must be unique per record type. They are the primary mechanism for idempotent upserts. [src1]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• searchMoreWithId pagination drift: Records created between search and searchMoreWithId calls can shift between pages, causing duplicates or missed records. Fix: Use timestamp-based filters and track processed records externally. [src8]
• Silent custom field failures: Setting a custom field with incorrect internalId does not raise an error — the field is silently ignored. Fix: Validate custom field script IDs against getCustomizationId before deployment. [src1]
• Concurrency starvation from long-running searches: Complex saved searches holding slots for 30+ seconds reduce capacity for all integrations. Fix: Break complex searches into narrower criteria; use async search for large result sets. [src3, src6]
• TBA token revocation without notification: Admin can revoke tokens at any time with no notification. Fix: Monitor for INVALID_LOGIN_ATTEMPT errors; implement alerting on auth failures. [src5]
• WSDL version mismatch after NetSuite upgrade: Pinning a retired WSDL version causes request failures. Fix: Monitor Oracle release notes; test against release preview accounts. [src1, src4]
• Timezone mismatches in date comparisons: Pacific Time default causes off-by-one errors near midnight. Fix: Always use full datetime (not date-only) in search criteria, explicitly in UTC. [src8]

Anti-Patterns

Wrong: Fetching all records to find changes

# BAD -- Pulls every customer record to detect changes
result = client.service.search(searchRecord={"basic": {}})
for record in result.searchResult.recordList.record:
    if record.lastModifiedDate > last_sync_time:
        process(record)

Correct: Use lastModifiedDate filter in search criteria

# GOOD -- Only fetches records modified since last sync
result = client.service.search(searchRecord={
    "basic": {
        "lastModifiedDate": {
            "operator": "after",
            "searchValue": last_sync_time.isoformat()
        }
    }
})

Wrong: Using search for known internal IDs

# BAD -- Using search when you know the IDs
for internal_id in known_ids:
    result = client.service.search(searchRecord={
        "basic": {"internalId": {"operator": "is", "searchValue": internal_id}}
    })

Correct: Use getList for known IDs (up to 1,000 per call)

# GOOD -- getList is faster, cheaper, and supports up to 1,000 records
ref_list = [{"type": "customer", "internalId": id} for id in known_ids[:1000]]
result = client.service.getList(baseRef=ref_list)

Wrong: Ignoring ExceededRequestLimitFault

# BAD -- No retry logic; integration fails on concurrency limit
try:
    result = client.service.addList(record=records)
except Exception as e:
    log.error(f"Failed: {e}")
    return None  # Gives up immediately

Correct: Implement exponential backoff with jitter

# GOOD -- Retries with increasing delay on concurrency limits
import time, random
for attempt in range(5):
    try:
        result = client.service.addList(record=records)
        break
    except ExceededRequestLimitFault:
        delay = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(delay)
else:
    raise RuntimeError("Exhausted retries")

Common Pitfalls

• Sandbox concurrency is fixed at 5: Production may have 50+ slots, but sandbox is always 5. Integration tests that pass in production timing may fail in sandbox. Fix: Design load tests with sandbox's 5-slot limit in mind. [src6, src7]
• searchMoreWithId results are not stable: Creating/modifying records between pagination calls causes result set drift. Fix: Track processed record IDs externally; use narrow date ranges. [src8]
• updateList at 100 vs addList at 200: Asymmetric limits catch developers who assume uniform caps. Fix: Always check per-operation limits; use asyncUpdateList (200) if needed. [src2]
• WSDL version pinning vs auto-upgrade: Not pinning means NetSuite upgrades may change behavior. Pinning too old risks hitting end-of-support. Fix: Pin to 2025.2; test against release preview before upgrades. [src1, src4]
• Saved search via SOAP ignores SearchPreferences: The saved search's own row limit overrides SOAP SearchPreferences. Fix: Set saved search to return all results; control pagination via SOAP pageSize. [src8]
• Custom record type naming: Custom types use customrecord_{id} where {id} is the numeric internal ID, not the script ID. Fix: Look up the numeric ID via Setup > Customization > Record Types. [src1]

Diagnostic Commands

# Check current concurrency usage
# Navigate in NetSuite: Setup > Integration > Integration Governance

# Test TBA authentication
curl -X POST \
  "https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/NetSuitePort_2025_2" \
  -H "Content-Type: text/xml" -H 'SOAPAction: "getServerTime"' \
  -d '<soap:Envelope...><soap:Header><!-- TBA header --></soap:Header><soap:Body><getServerTime/></soap:Body></soap:Envelope>'

# Check WSDL availability
curl -s "https://ACCOUNT_ID.suitetalk.api.netsuite.com/wsdl/v2025_2_0/netsuite.wsdl" | head -5

# Monitor async job status
# Use getAsyncResult with jobId from async operation
# Poll until status is "complete" or "failed"

Version History & Compatibility

SOAP Removal Timeline

When to Use / When Not to Use

Important Caveats

• Concurrency limits vary dramatically by service tier and SC+ licensing. A Standard tier account with no SC+ licenses has only 5 concurrent slots shared across all API surfaces. [src3, src6]
• SOAP is on a hard deprecation path. The 2028.2 removal date is firm per Oracle's FAQ. Do not start new SOAP integrations. [src4]
• Governance unit costs per operation are not fully documented publicly. Approximate values in this card are based on community analysis. [src6]
• Sandbox/developer accounts are capped at 5 concurrent requests regardless of production tier. Performance testing in sandbox does not represent production throughput. [src6, src7]
• Rate limits (requests per minute/day) are enforced but exact thresholds are not publicly documented. Plan for thousands of calls per minute for large accounts. [src6]