A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The NetSuite API is how an app or AI agent works with a NetSuite account: reading and writing records like customers and items, creating transactions such as invoices and sales orders, and running queries across any record. Access is granted through an OAuth 2.0 or token-based credential, and that credential runs as a NetSuite role whose permissions, not a granular per-method scope, set what each call can read or change. NetSuite ships two named releases a year while the REST record and query services stay under a stable version, so paths do not move when records and operations are added.
How an app or AI agent connects to NetSuite determines what it can reach. There is a REST route for reading and writing records, a route for running queries, and a hosted server that exposes NetSuite tools to agents, and each is governed by the token behind it and the NetSuite role that token runs as.
The REST record service reads and writes records under /services/rest/record/v1/{recordType} with GET, POST, PATCH, and DELETE, and the query service runs SuiteQL with a POST to /services/rest/query/v1/suiteql. Both are reached at the account-specific host accountId.suitetalk.api.netsuite.com and return JSON described by OpenAPI 3.0 metadata. A call authenticates with an OAuth 2.0 bearer token or a TBA signature and runs as the underlying NetSuite role.
The NetSuite AI Connector Service is Oracle's first-party Model Context Protocol server, delivered as the MCP Standard Tools SuiteApp. It exposes tools for creating and updating records, running SuiteQL from natural language, running saved searches, and viewing reports, and supports custom tools. It uses OAuth 2.0 with per-agent consent and the same role-based permissions as the NetSuite UI, so an agent reaches only what its role and the MCP Server Connection permission allow. Production-ready MCP integration with AI clients shipped in the 2026.1 release.
RESTlets are custom server-side scripts written in SuiteScript and deployed as REST endpoints under /services/rest/restlet, for logic the standard record and query services do not cover. They authenticate with the same OAuth 2.0 or TBA credentials, using the separate restlets scope, and run as the NetSuite role behind the token.
The authorization-code grant signs a user in to NetSuite and exchanges the resulting code for a bearer access token. The token carries the rest_webservices scope and runs as the signed-in user's NetSuite role, so the role sets what it can reach. The integration record must have REST Web Services enabled.
The client-credentials flow lets a server integration get a bearer token with no user present, using a signed assertion mapped to a NetSuite role and entity. The token carries the rest_webservices scope and runs as that mapped role, which is the access boundary for an unattended agent.
TBA is NetSuite's OAuth 1.0a model: each request is signed with a consumer key pair and a token key pair, with no expiring access token. It runs as the role tied to the token. From the 2027.1 release new integrations can no longer be created with TBA, though existing ones keep working.
The SuiteTalk REST API is split into areas an agent can act on, like customer records, transactions such as invoices and sales orders, vendor bills, and ad-hoc queries over any record. Each call runs as a NetSuite role, and writes in the transaction areas change real financial records.
Read and write customer records.
Sales-side transactions like invoices and sales orders.
Vendor records and vendor bills.
Product and service item records.
SuiteQL queries and the metadata catalog.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CustomersRead and write customer records.5 | ||||||
| GET | /record/v1/customer | List customer records as a collection, paged with limit and offset. | read | rest_webservices | Current | |
Read access is decided by the NetSuite role the token runs as, not the scope. Acts oncustomer Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/customer/{id} | Retrieve a single customer record by internal id. | read | rest_webservices | Current | |
Read-only; visibility follows the role. Acts oncustomer Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/customer | Create a customer record. | write | rest_webservices | Current | |
Needs a role with create permission on customers; can carry X-NetSuite-Idempotency-Key. Acts oncustomer Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /record/v1/customer/{id} | Update fields on an existing customer record. | write | rest_webservices | Current | |
PATCH applies a partial update; needs role edit permission on customers. Acts oncustomer Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /record/v1/customer/{id} | Delete a customer record. | write | rest_webservices | Current | |
Irreversible; needs role delete permission on customers. Acts oncustomer Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Transactions (sales)Sales-side transactions like invoices and sales orders.8 | ||||||
| GET | /record/v1/invoice | List invoice transactions as a collection. | read | rest_webservices | Current | |
Read-only; visibility follows the role. Acts oninvoice Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/invoice/{id} | Retrieve a single invoice by internal id. | read | rest_webservices | Current | |
Read-only. Acts oninvoice Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/invoice | Create an invoice transaction. | write | rest_webservices | Current | |
Creates a real financial record; needs role create permission on invoices. Acts oninvoice Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /record/v1/invoice/{id} | Update an existing invoice transaction. | write | rest_webservices | Current | |
Partial update; needs role edit permission on invoices. Acts oninvoice Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/salesOrder | List sales order transactions as a collection. | read | rest_webservices | Current | |
Read-only; visibility follows the role. Acts onsalesOrder Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/salesOrder/{id} | Retrieve a single sales order by internal id. | read | rest_webservices | Current | |
Read-only. Acts onsalesOrder Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/salesOrder | Create a sales order transaction. | write | rest_webservices | Current | |
Creates a real transaction; needs role create permission on sales orders. Acts onsalesOrder Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/salesOrder/{id}/!transform/invoice | Transform a sales order into an invoice, carrying its lines forward. | write | rest_webservices | Current | |
A record transformation; creates an invoice from the order. Needs create permission on invoices. Acts onsalesOrder Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Purchasing & vendorsVendor records and vendor bills.5 | ||||||
| GET | /record/v1/vendor | List vendor records as a collection. | read | rest_webservices | Current | |
Read-only; visibility follows the role. Acts onvendor Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/vendor | Create a vendor record. | write | rest_webservices | Current | |
Needs a role with create permission on vendors. Acts onvendor Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/vendorBill | List vendor bill transactions as a collection. | read | rest_webservices | Current | |
Read-only; visibility follows the role. Acts onvendorBill Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/vendorBill | Create a vendor bill (payables) transaction. | write | rest_webservices | Current | |
Creates a real payables record; needs role create permission on vendor bills. Acts onvendorBill Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /record/v1/vendorBill/{id} | Update an existing vendor bill transaction. | write | rest_webservices | Current | |
Partial update; needs role edit permission on vendor bills. Acts onvendorBill Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsProduct and service item records.3 | ||||||
| GET | /record/v1/inventoryItem | List inventory item records as a collection. | read | rest_webservices | Current | |
Read-only; visibility follows the role. Acts oninventoryItem Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/inventoryItem/{id} | Retrieve a single inventory item by internal id. | read | rest_webservices | Current | |
Read-only. Acts oninventoryItem Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /record/v1/inventoryItem | Create an inventory item record. | write | rest_webservices | Current | |
Changes the item catalog; needs role create permission on items. Acts oninventoryItem Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Query & metadataSuiteQL queries and the metadata catalog.2 | ||||||
| POST | /query/v1/suiteql | Run a SuiteQL (SQL-dialect) query across records; the statement goes in the q field of the JSON body. | read | rest_webservices | Current | |
Requires the Prefer: transient header. A query reads only what the role can see; up to 100,000 results. Acts onsuiteql Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /record/v1/metadata-catalog | Retrieve the OpenAPI 3.0 metadata catalog describing record types, fields, and operations. | read | rest_webservices | Current | |
Read-only; describes the schema the role can work with. Acts onmetadata-catalog Permission (capability) rest_webservicesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| Event | What it signals | Triggered by |
|---|
NetSuite governs how many requests an integration can run at the same time rather than capping a per-second rate. The concurrency limit is set by the account's service tier and the number of SuiteCloud Plus licenses, and is shared across REST and SOAP.
NetSuite governs by concurrency, the number of requests an integration runs at the same time, rather than a fixed per-second rate. The base concurrent-request limit is set by the account's service tier, 5 for shared and development or partner accounts, 15 for Service Tier 1, and 20 for Service Tier 2 and Ultimate, and rises by 10 for each SuiteCloud Plus license, so a Tier 1 account with five SuiteCloud Plus licenses allows 65. REST and SOAP draw on the same global pool. A request that exceeds the limit returns HTTP 429 with the error code CONCURRENCY_LIMIT_EXCEEDED, and the account's limit is shown on the Integration Governance page.
Record collections and SuiteQL results are paged with the limit and offset query parameters, where limit sets the page size and offset the starting position. A SuiteQL request must carry the Prefer: transient header, and the response includes hasMore, count, totalResults, and next and previous links for walking the pages.
A SuiteQL query returns at most 100,000 results in total; larger extracts use SuiteAnalytics Connect. A record collection page returns up to 1,000 records, set by limit. A write can carry the X-NetSuite-Idempotency-Key header, a UUID, so a retried request is not applied twice.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_CONTENT / INVALID_REQUEST | The request body or parameters were invalid, like a bad field value, a malformed payload, or an unsupported parameter. The response names the offending field in o:errorPath. | Read the detail and o:errorPath in o:errorDetails, fix the payload or parameter, and resend. The request is not retryable as-is. |
| 401 | INVALID_LOGIN | Authentication failed: the OAuth token or TBA signature was missing, expired, or invalid. | Refresh or reissue the token, confirm the integration has REST Web Services enabled, and resend. |
| 403 | INSUFFICIENT_PERMISSION | The token authenticated but the NetSuite role it runs as lacks permission for the record or action requested. | Grant the role the needed record and action permissions in NetSuite, or use a token whose role allows it. The role is the boundary. |
| 404 | NONEXISTENT_ID | The requested record or sub-resource does not exist, or is not visible to this role. | Verify the record type and internal id, and confirm the role can see the record. |
| 429 | CONCURRENCY_LIMIT_EXCEEDED | Too many requests ran at the same time and the account's concurrency limit was hit. NetSuite governs by concurrency, not a per-second rate. | Lower the number of in-flight requests, back off and retry, and add SuiteCloud Plus licenses if more concurrency is needed. |
| 500 | UNEXPECTED_ERROR | An error on NetSuite's side. It is uncommon. | Retry with backoff, and contact NetSuite support if it persists. |
NetSuite ships two named releases a year, like 2026.1, and the REST record and query services sit under a stable v1 path that does not change with each release. New records and capabilities are added to REST every cycle.
The SuiteTalk REST record service (/record/v1) and query service (/query/v1) sit under a stable v1 path that does not change with each named release. NetSuite ships two named releases a year, and new record types, operations, and fields are added to REST every cycle without minting a new path version.
A named release focused on closing remaining REST gaps so integrations can move off SOAP, plus production-ready Model Context Protocol integration with commercial AI systems.
With the 2025.2 endpoint NetSuite delivered its last scheduled SOAP WSDL, marking REST as the forward path for SuiteTalk integrations.
An announced future change: from the 2027.1 release, new integrations can no longer be created using Token-Based Authentication with SOAP, REST, or RESTlets. Existing TBA integrations continue to work.
The REST v1 path is stable across releases; new records and operations are added each cycle.
NetSuite release notes ↗Bollard AI sits between a team's AI agents and NetSuite. Grant each agent exactly the access it needs, read or write, record type by record type, and every call is checked and logged.