> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twinbay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# NetSuite

> Customers, accounts and items, with invoices, the payments that settle them, and SuiteQL

An ERP account's books over the NetSuite REST Web Services API: customers, the chart of accounts, the items an invoice bills for, invoices with sublists and server-computed totals, the customer payments that settle them, SuiteQL over the analytics tables, and the metadata catalog. Oracle ships no Python client for REST Web Services, so the conformance suite pins `netsuite` — the one maintained client the ecosystem uses — and drives the container through the sequence an ERP integration actually runs.

**Slug:** `netsuite`

## The account is in the realm and the host

One container serves one account, and the account id appears in two spellings of the same value: uppercased with an underscore in the OAuth `realm` (`1234567_SB1`), lowercased and hyphenated in the host (`1234567-sb1.suitetalk.api.netsuite.com`). A request naming another account is an authentication failure, never a `404` and never an empty collection.

## What it models

| Area                 | Modelled                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The account          | A furnished account: one subsidiary, its currency and the company information, a chart of accounts (`Accounts Receivable`, `Consulting Income`), one non-inventory item and one customer                                                                                                                                                                                                                           |
| Authentication       | TBA OAuth 1.0a (`HMAC-SHA256`, realm, signed method, URL and parameters — verified here), OAuth 2.0 bearer, one indistinguishable `401 INVALID_LOGIN` for every bad attempt, `403 INSUFFICIENT_PERMISSION` for a role that lacks permission, and `429 SSS_REQUEST_LIMIT_EXCEEDED` for exhausted concurrency                                                                                                        |
| Customers            | Create, read, `?q=` search, `?fields=` projection, update, and delete-with-inactivation; `balance` from unpaid invoices and `overduebalance` derived from the due dates against the clock                                                                                                                                                                                                                          |
| Accounts and items   | Create, read, list, search, projection and update; items as `noninventoryitem` and `service` — two paths into one record type, one id sequence, and an item's income account resolved rather than trusted                                                                                                                                                                                                          |
| Invoices             | Create with an `item` sublist, read with `expandSubResources`, PATCH that merges by default and replaces under `?replace=item`, `subtotal` and `total` from the lines with `taxTotal` always zero, `amountpaid`/`amountremaining` from the payments, `tranId` from the account's numbering, `status` through `Open` → `Paid In Full` with `Voided` reachable from `Open`, voiding and deleting with their refusals |
| Payments             | `customerpayment` against open invoices of its own customer, each line held to what the invoice owes, `applied`/`unapplied`, and the effect on the invoice and the customer                                                                                                                                                                                                                                        |
| SuiteQL              | `SELECT` of named columns or `*` from `customer` or `transaction`, equality `WHERE`, `Prefer: transient` required, `limit`/`offset` as parameters never in the statement                                                                                                                                                                                                                                           |
| The metadata catalog | An OpenAPI-shaped document of exactly the record types the twin models, narrowed by `select`, and a JSON Schema per type where a reference is an object                                                                                                                                                                                                                                                            |
| Idempotency          | `X-NetSuite-Idempotency-Key` on writes: a replay returns the original response, including the original `Location`, and does not act twice; reuse with a different request is an error                                                                                                                                                                                                                              |
| Paging               | Offset paging everywhere: `limit` defaulting to `1000` and capping at it, `limit=0`/negative/non-numeric refused, ascending internal id as a total order, `count`/`hasMore`/`offset`/`totalResults` and `next`/`last` links                                                                                                                                                                                        |

Advancing the sandbox runs the arithmetic of the books again: an invoice against the payments applied to it. A customer's balance and overdue balance are derived on the way out rather than stored, so they move with the invoices and the clock without anything being written.

## Scenarios

`overdue-receivables`, `concurrency-exhausted`, `restricted-role`.

## Not modelled

The OAuth 1.0a and 2.0 authorization dances — the twin is handed live credentials. SuiteTalk SOAP, RESTlets, SuiteScript, workflows and approval routing, inventory and fulfilment, custom records and fields, saved searches, and OneWorld consolidation beyond the one seeded subsidiary. Taxes: `taxTotal` is always zero. Deleting a payment, and editing one, because both would move a receivable that has already been read.

Nobody who built this twin had a NetSuite account, so a handful of envelopes and codes had to be chosen from Oracle's documentation rather than read off a live one — the strings inside `INSUFFICIENT_PERMISSION` and `SSS_REQUEST_LIMIT_EXCEEDED`, the unknown-id refusal, the idempotency window, and the unexpanded shape of a sublist. The twin's own README lists them under **Where the docs do not reach**.