NetSuite SOAP to REST Migration Before the SOAP Retirement
A NetSuite SOAP to REST migration should begin with a business-flow inventory and a testable replacement plan. Changing the endpoint and converting XML to JSON are only part of the work. The replacement must preserve customer identity, transaction lines, approval behavior, accounting results and recovery after a failed connection.
Start now with discovery, even if the eventual production change is scheduled later. An integration used once a quarter can be easy to miss and difficult to replace during a close. A connector maintained by a supplier also needs a named owner and a confirmed migration path.
This guide explains how to build the migration plan, what to test and how to decide when a flow is ready to change over.
Understand the retirement milestones
Oracle identifies 2025.2 as the last planned SOAP endpoint. Its removal FAQ says new SOAP integrations cannot be built from NetSuite 2027.1, when new integrations using token-based authentication are restricted. Existing SOAP integrations continue until their applicable endpoint is disabled; all SOAP endpoints are scheduled to be disabled in 2028.2. Oracle recommends REST web services with OAuth 2.0 for new work. These are release milestones, not a single calendar date for every account.
There is an important documentation discrepancy to verify when planning an older endpoint upgrade. The detailed FAQ and its matrix show 2027.2 as the point when only the final endpoint remains supported. A shared warning on the WSDL support page says 2027.1. Confirm the applicable support position with Oracle rather than treating the intermediate date as settled.
Inventory business flows before estimating effort
Make one row for each business flow, not merely one row per integration application. A single connection may import orders, export stock, retrieve invoices and move attachments. Those flows can have different owners, replacement methods and failure consequences.
Record:
- Business purpose and operational owner
- Source system, destination and direction
- SOAP endpoint, application and deployment owner
- Records, fields, sublists and operations used
- Frequency, peak periods and maximum acceptable delay
- Authentication method and role
- Existing identifiers and duplicate-prevention controls
- Recovery method and downstream reconciliation
- Vendor responsibility, support contact and confirmed replacement plan
Use observed traffic as one source of evidence. Oracle's SOAP Web Services Analysis shows operation performance and API-version usage. However, APM web-services analysis covers synchronous requests. Reconcile it with application configuration, job schedules, deployment records and supplier confirmation so that asynchronous or infrequent work is not missed.
Mark a flow as unknown until someone resolves the gap. A row with an unconfirmed owner should remain visible in the migration plan.
Prove coverage at the operation and field level
A supported record is only the starting point. The migration team must establish whether the intended channel supports the required operation, fields, subrecords and transaction behavior in the target account.
Oracle publishes a SOAP-to-REST operation comparison and a supported-record matrix. Use these to identify candidate replacements, then inspect the actual account metadata. For example, the upgrade guide maps update operations to PATCH and upsert to PUT, but the surrounding request and response behavior still needs testing.
Build a parity ledger with five columns:
- Existing business action
- Candidate REST operation or approved alternative
- Required data and dependencies
- Expected business result
- Evidence and unresolved differences
For an order update, “request succeeded” is insufficient. Check whether the correct line changed, unmentioned lines remained intact, quantities stayed valid and required approvals still occurred. Include a closed order, a partially fulfilled order and a rejected change in the test set.
The REST metadata catalog describes available resources, fields, sublists, subrecords and methods. It reflects the account's customizations and the user's view, so inspect it with the intended integration identity.
Choose an alternative for each genuine gap
Separate a product gap from a permissions problem, an incorrect identifier and an assumption carried over from SOAP. Each can look like a missing capability but requires a different response.
Where the native REST operation meets the requirement, prefer a design the team can support with documented behavior. Where it does not, evaluate a RESTlet, a supported connector capability or a change to the business flow. Record why the alternative is necessary, who maintains it and how it will be retested.
Avoid turning every uncertain mapping into custom code. A short proof of concept can establish whether a standard operation is sufficient before development starts. Equally, do not promise one-to-one SOAP parity without examining the actual record and action.
The scope of a NetSuite integration assessment should include this decision work. A count of endpoints alone is a weak basis for estimating migration effort.
Treat authentication as an operational dependency
Design the replacement identity, role and lifecycle before the final rehearsal. The application needs only the data and actions required for its purpose, plus the relevant authentication permissions. An administrator role can conceal permission defects during testing and grants unnecessarily broad access.
For machine-to-machine OAuth 2.0, account setup is environment-specific. Oracle says client-credentials mappings are not copied to another production account, Release Preview or sandbox, and are cleared by a sandbox refresh. Include rebuilding and verifying that setup in the rehearsal plan.
The runbook should name the certificate owner, storage location for the private key, expiry monitoring process and emergency escalation route. Store references to secret material in the documentation, never the secret itself. Test authorized renewal and revocation procedures before depending on them during an incident.
Rehearse failure and uncertain outcomes
A realistic migration test deliberately interrupts the flow. Useful cases include an expired credential, a missing reference, a connection failure after submission, an unavailable downstream system and a backlog accumulated during an outage.
For each case, the operator should be able to answer three questions:
- Did NetSuite create or change the intended record?
- Can the business event be retried safely?
- What evidence proves the flow is complete?
Keep source identifiers and target identifiers together. A recovery attempt must determine whether it is completing the original event or starting a new one. Measure unresolved business events as well as HTTP errors.
For long-running asynchronous REST work, Oracle documents job identifiers, status retrieval and an idempotency retry mechanism. Incorporate those capabilities into the design when that execution model fits; do not apply their exact behavior to unrelated synchronous requests.
A hypothetical order migration
Consider a distributor whose SOAP application creates sales orders and later adds carrier tracking information. Discovery reveals that the two actions run in different jobs. The order import runs every few minutes, while tracking updates run overnight.
The team separates them into two migration units. For order creation, its test pack includes a new customer, an existing customer, a duplicate event, a missing item and an order requiring approval. For tracking updates, it tests partial fulfillment and multiple packages rather than assuming one order has one tracking number.
During rehearsal, the replacement creates the correct order but the source system times out before saving the NetSuite identifier. The recovery test finds the existing order using the agreed business identifier and continues without creating another order. A second test proves that the tracking update leaves unaffected shipment information intact.
This hypothetical example illustrates the acceptance evidence to seek. It is not a reported CuriousRubik customer outcome or an assertion about every connector's standard behavior.
Define the cutover and rollback boundary
Plan for one authorized writer per business event during the transition. If old and new integrations both create orders, a comparison exercise can become a duplication incident. Shadow testing should use a controlled nonproduction destination or a read-only comparison unless a safe production design has been explicitly established.
Before switching, record the final old-system checkpoint, queued events, outstanding failures and the expected first event for the replacement. Reconcile source events to target records after the switch. A transport-level success count alone cannot prove completeness.
Define the last point at which rollback remains straightforward. Once new transactions have been fulfilled, paid or consumed downstream, returning to the old writer may require a managed recovery rather than simply restarting the previous job. Agree who can authorize that decision and which business evidence they need.
Decide whether the flow is ready
A release decision should require complete ownership, approved coverage, successful failure tests, reconciled results, prepared support and a documented transition boundary. Open issues must have a named risk owner and an explicit decision. Do not hide a blocked critical operation inside a high overall test pass rate.
After the change, observe at least the meaningful business cycle for that flow. A daily order import and a month-end export need different verification windows. Include the migration in the ongoing NetSuite support handover so that future administrators can understand the replacement and its recovery process.
Frequently asked questions
Does upgrading to SOAP 2025.2 remove the need to migrate
No. An endpoint upgrade may address an immediate compatibility issue, but Oracle's plan still removes SOAP in 2028.2. Assess the short-term fix and the replacement as separate decisions.
Can the team migrate one integration at a time
Often, but sequence by business dependency. Shared master data, transaction identifiers and downstream actions can tie several flows together. Document the boundary before choosing the release unit.
Is REST automatically faster for every business flow
No. Measure the complete process with representative data and account load. Call count, scripts, request size, concurrency and downstream work all influence the result.
What if a required SOAP action has no direct REST equivalent
Confirm the current operation documentation and account behavior first. Then evaluate an approved RESTlet, connector capability or redesigned process, with its own support and testing requirements.
What should the business owner approve
The expected transaction result, reconciliation evidence, unresolved risks, operating procedure and recovery boundary. Technical connectivity by itself does not establish business readiness.
Related reading
Related reading
