/records-and-metadata

name: "NetSuite Records & Metadata"
description: >
  Retrieving individual NetSuite records by type and internal ID, and
  discovering a record type's available fields via record-type metadata.
  Read-only — retrieving existing records, not creating or updating them.
when_to_use: >-
  When looking up a specific NetSuite record (customer, vendor, sales
  order, invoice, or any other record type) by its internal ID, or when
  you need to know what fields a NetSuite record type has before querying
  or reading it. Use when: netsuite record, netsuite customer, netsuite
  vendor, netsuite invoice, netsuite sales order, record type, internal
  id, or netsuite field.

NetSuite Records & Metadata

Overview

NetSuite organizes almost everything as a typed record — `customer`, `vendor`, `salesorder`, `invoice`, `employee`, and many more, each with its own internal ID and field set. This skill covers looking a specific record up directly when you already know (or can pin down) its type and ID, and discovering what fields a record type actually has before you go looking for one.

Anti-triggers

• **Finding records by criteria you don't have an ID for** — use

`suiteql-queries` to search, then retrieve the specific record here if needed.

• **Creating or updating a record** — this plugin is read-only. See

[GOVERNANCE.md](../../GOVERNANCE.md), *Tool permission tiers*: `ns_createRecord` and `ns_updateRecord` are the two write tools this plugin deliberately excludes. Make the change directly in the NetSuite UI, with the same care you'd give any change to a client's financial system of record.

• **Reports or saved searches already built for this data** — use

`reports-and-saved-searches` rather than re-deriving what a report already computes.

• **Auth, role permissions, or error handling** — use `api-patterns`.

Core Concepts

Every NetSuite record has a record type (a fixed string like `customer` or `salesorder`) and an internal ID (a number, unique within that type). Record-type metadata describes the fields a given type carries — names, data types, and (per NetSuite's `ns_getRecordTypeMetadata` tool) can be requested for a single type or for all types at once. What a record actually returns when retrieved depends entirely on the connected role's view permissions on that type and its fields — the same way it would if a human opened the record in the NetSuite UI.

API Patterns

The confirmed read tool family for this domain:

• `ns_getRecord` — retrieves a record in NetSuite by type and internal ID
• `ns_getRecordTypeMetadata` — retrieves metadata (available fields and

data types) for all NetSuite record types, or for a specific type

Both are documented by Oracle at [Available Tools in the MCP Standard Tools SuiteApp](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_0902023508.html). The corresponding write tools, `ns_createRecord` and `ns_updateRecord`, are excluded from this plugin — see [GOVERNANCE.md](../../GOVERNANCE.md).

**A note on record-type-specific commands:** this plugin does not ship a separate command per record type (e.g. no dedicated "get customer" vs. "get vendor" command). `ns_getRecord` is generic across record types by design, and this plugin's `/get-record` command is built directly against that generic tool rather than inventing per-type wrappers that don't correspond to anything the underlying MCP surface exposes.

Common Workflows

Looking up a customer before an escalation

A support ticket references a customer by name, not ID:

1. If the internal ID isn't known, use `suiteql-queries` to find it (e.g. `SELECT id, companyname FROM customer WHERE companyname LIKE '...'`) 2. Call `ns_getRecord` with type `customer` and the resolved ID 3. Report the fields relevant to the escalation — don't dump the entire record if only a few fields matter

Confirming a record type's fields before writing a SuiteQL query

Before querying an unfamiliar record type:

1. Call `ns_getRecordTypeMetadata` for that type 2. Use the returned field names and types to write an accurate SuiteQL query in `suiteql-queries`, rather than guessing at field names

Gotchas

• **Retrieval respects the connected role's field-level permissions, not

just record-level.** A role with view access to a record type can still have specific fields withheld — a retrieved record missing an expected field may be a permission boundary, not a data gap.

• **Internal IDs are per-type, not global.** Customer 12345 and sales

order 12345 are unrelated records; always pair an ID with its record type.

• **This is a read-only lookup, with no exceptions.** Even a trivial

correction (fixing an obviously wrong field) is outside this plugin — escalate to a human with direct NetSuite access.

Related Skills

• [Reports & Saved Searches](../reports-and-saved-searches/SKILL.md) — Pre-built aggregations and lookups
• [SuiteQL Queries](../suiteql-queries/SKILL.md) — Finding records by criteria
• [API Patterns](../api-patterns/SKILL.md) — Auth, roles, and error handling