NetSuite Automation

What this skill does

# NetSuite Automation

Automate Oracle NetSuite ERP operations including creating customers and sales orders, running SuiteQL queries, upserting records by external ID, and inspecting record metadata for comprehensive business management.

**Toolkit docs:** [composio.dev/toolkits/netsuite](https://composio.dev/toolkits/netsuite)

---

## Setup

This skill requires the **Rube MCP server** connected at `https://rube.app/mcp`.

Before executing any tools, ensure an active connection exists for the `netsuite` toolkit. If no connection is active, initiate one via `RUBE_MANAGE_CONNECTIONS`.

---

## Core Workflows

### 1. Create Sales Orders

Create customer orders with line items including item references, quantities, and pricing.

**Tool:** `NETSUITE_CREATE_SALES_ORDER`

**Key Parameters:**
- `entity` (required) -- Customer reference: `{"id": "<internal_id>"}`
- `item` (required) -- Container with `items` array, each containing:
  - `item` (required) -- Item reference: `{"id": "<internal_id>"}`
  - `quantity` (required) -- Units to order (non-negative)
  - `rate` -- Unit price (optional if item has default pricing)
  - `amount` -- Total line amount (alternative to rate)
  - `taxcode` -- Tax code reference: `{"id": "<internal_id>"}` (required if SuiteTax enabled)
  - `description` -- Line item notes
- `tranDate` -- Transaction date in `YYYY-MM-DD` format
- `memo` -- Header memo
- `orderStatus` -- `"A"` (Pending Approval) or `"B"` (Pending Fulfillment)
- `otherrefnum` -- External reference or PO number

**Example:**
```
Tool: NETSUITE_CREATE_SALES_ORDER
Arguments:
  entity: {"id": "1234"}
  item: {
    "items": [
      {"item": {"id": "56"}, "quantity": 10, "rate": 25.00},
      {"item": {"id": "78"}, "quantity": 5, "rate": 50.00}
    ]
  }
  tranDate: "2026-02-11"
  memo: "Q1 bulk order"
  orderStatus: "B"
```

---

### 2. Run SuiteQL Queries

Execute ad-hoc SQL queries against NetSuite data with server-side paging.

**Tool:** `NETSUITE_RUN_SUITEQL_QUERY`

**Key Parameters:**
- `q` (required) -- SuiteQL SELECT statement
- `limit` -- Rows per page (default varies)
- `offset` -- Zero-based index of first row (must be a multiple of `limit`)

**Examples:**
```
Tool: NETSUITE_RUN_SUITEQL_QUERY
Arguments:
  q: "SELECT id, companyname, email FROM customer WHERE isinactive = 'F' ORDER BY companyname"
  limit: 100
  offset: 0
```

```
Tool: NETSUITE_RUN_SUITEQL_QUERY
Arguments:
  q: "SELECT id, entitystatus, total FROM transaction WHERE type = 'SalesOrd' AND trandate >= '2026-01-01'"
  limit: 50
```

---

### 3. Create and Manage Customers

Create new customer records with subsidiary assignment and contact details.

**Tools:**
- `NETSUITE_CREATE_CUSTOMER` -- Create a new customer
- `NETSUITE_GET_CUSTOMER` -- Retrieve customer by internal ID
- `NETSUITE_UPDATE_CUSTOMER` -- Update existing customer (PATCH semantics)

**Key Parameters for `NETSUITE_CREATE_CUSTOMER`:**
- `body` (required) -- JSON object with customer data. Required fields:
  - `subsidiary` -- Object with `id` (subsidiary internal ID)
  - Either `companyName` (for businesses) or `firstName` + `lastName` (for individuals)
  - Optional: `email`, `phone`, `isPerson` (set to `"T"` for individuals), `comments`
- `replace` -- Comma-separated sublist names to fully replace (e.g., `"contacts,addressbook"`)

**Example:**
```
Tool: NETSUITE_CREATE_CUSTOMER
Arguments:
  body: {
    "companyName": "Acme Corp",
    "subsidiary": {"id": "1"},
    "email": "[email protected]",
    "phone": "555-0100"
  }
```

---

### 4. Upsert Records by External ID

Create or update records idempotently using an external identifier. Essential for sync workflows.

**Tool:** `NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID`

**Key Parameters:**
- `record_type` (required) -- Record type name, e.g., `"customer"`, `"salesorder"`, `"customrecord_myrec"`
- `external_id` (required) -- External ID value (letters, numbers, underscore, hyphen only)
- `body` (required) -- JSON object matching the record schema; include mandatory fields when creating

**Example:**
```
Tool: NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID
Arguments:
  record_type: "customer"
  external_id: "CRM-CUST-42"
  body: {
    "companyName": "Acme Corp",
    "subsidiary": {"id": "1"},
    "email": "[email protected]"
  }
```

> **Warning:** Idempotency depends on consistent external ID usage. Mismatches silently create additional records instead of updating.

---

### 5. Inspect Record Metadata

Discover available fields, data types, constraints, and requirements before creating or updating records.

**Tool:** `NETSUITE_GET_RECORD_METADATA`

**Key Parameters:**
- `record_type` (required) -- e.g., `"customer"`, `"salesorder"`, `"invoice"`, `"vendor"`, `"employee"`, `"item"`
- `accept` -- `"application/schema+json"` (default, JSON Schema) or `"application/swagger+json"` (OpenAPI 3.0)

**Example:**
```
Tool: NETSUITE_GET_RECORD_METADATA
Arguments:
  record_type: "salesorder"
```

---

### 6. List and Filter Records

Retrieve multiple records with optional filtering and pagination.

**Tool:** `NETSUITE_LIST_RECORDS`

**Key Parameters:**
- `recordType` (required) -- e.g., `"customer"`, `"salesorder"`
- `q` -- Filter expression using N/query operators, e.g., `"email START_WITH \"barbara\""`
- `limit` -- Max records per page (1--1000, default 1000)
- `offset` -- Zero-based index (must be divisible by limit)

**Supporting Tools:**
- `NETSUITE_FILTER_RECORD_COLLECTION` -- Alternative filtering (secondary to SuiteQL)
- `NETSUITE_GET_RECORD_SELECTED_FIELDS` -- Retrieve specific fields only (reduced payload)

---

## Recommended Execution Plan

1. **Inspect the record schema** using `NETSUITE_GET_RECORD_METADATA` to discover required fields
2. **Search for existing records** using `NETSUITE_RUN_SUITEQL_QUERY` to avoid duplicates
3. **Look up customer** by email using SuiteQL; fetch details with `NETSUITE_GET_CUSTOMER` if found
4. **Create customer if needed** using `NETSUITE_CREATE_CUSTOMER` (ensure `subsidiary` is set)
5. **Validate item internal IDs** using `NETSUITE_LIST_RECORDS` or SuiteQL
6. **Create the sales order** using `NETSUITE_CREATE_SALES_ORDER` with validated references
7. **Optionally upsert by external ID** using `NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID` for sync workflows
8. **Verify results** using `NETSUITE_GET_RECORD_SELECTED_FIELDS` to confirm pricing/totals

---

## Known Pitfalls

| Pitfall | Detail |
|---------|--------|
| **Invalid item IDs** | `NETSUITE_CREATE_SALES_ORDER` throws USER_ERROR when item internal ID is invalid. Pre-validate via `NETSUITE_LIST_RECORDS` or `NETSUITE_RUN_SUITEQL_QUERY`. |
| **Missing required fields** | `NETSUITE_CREATE_CUSTOMER` returns 400 when required fields (e.g., `subsidiary`) are missing. Always inspect with `NETSUITE_GET_RECORD_METADATA` first. |
| **SuiteQL field names** | Query differences by account can cause empty results. Confirm field names via `NETSUITE_GET_RECORD_METADATA` when results look wrong. |
| **Filter expression limits** | `NETSUITE_FILTER_RECORD_COLLECTION` may fail if filter syntax is unsupported. Treat as secondary to SuiteQL. |
| **External ID idempotency** | `NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID` depends on consistent external IDs. Mismatches silently create duplicates instead of updating. |
| **SuiteTax line items** | Accounts with SuiteTax enabled require `taxcode` on every line item. Omitting it causes creation failures. |

---

## Quick Reference

| Tool Slug | Description |
|-----------|-------------|
| `NETSUITE_CREATE_SALES_ORDER` | Create a new sales order with line items |
| `NETSUITE_RUN_SUITEQL_QUERY` | Execute ad-hoc SuiteQL queries with paging |
| `NETSUITE_CREATE_CUSTOMER` | Create a new customer record |
| `NETSUITE_GET_CUSTOMER` | Retrieve a customer by internal ID |
| `NETSUITE_UPDATE_CUSTOMER` | Update an existing customer (PATCH) |
| `NETSUITE_UPSERT_RECORD_BY_EXTERNAL_ID` | Create or update a record by external ID |
| `NETSUITE_GET_RECORD_METADATA` | Inspect record schema and field definitions |
| `NETSUI