NetSuite MCP API

How it works

This API processes customer service emails and interacts with NetSuite. A classifier analyzes incoming emails and outputs structured JSON, which this API uses to query or write data to NetSuite via Claude AI agents.

End-to-End Flow

1. Email Classification

The classifier prompt analyzes emails and extracts:

• Customer identity (email, name, company)
• Questions grouped by workflow type
• PDF/attachment data (PO items, SKUs, quantities)
• Boolean flags for which workflows to run

2. Workflow Routing

Based on classifier output, the API routes to appropriate workflows:

3. NetSuite Interaction

Claude AI agents execute SuiteQL queries and return structured data. For po2so workflow, agents can also create records.

Expected Input Format

The classifier produces this JSON structure, which becomes the API request body:

{
  "customer_email": "buyer@acmecorp.com",
  "customer_name": "Jane Doe",
  "customer_company": "ACME Corp",
  
  "has_po2so": false,
  "has_stock_price": true,
  "has_ship_date": false,
  "has_hold": false,
  "has_other": false,
  
  "po2so_questions": [],
  "stock_price_questions": [
    {
      "index": 0,
      "normalized_question": "What is the price for item SKU-001?",
      "source_quote": "can you send pricing for SKU-001?",
      "item_hints": ["SKU-001"],
      "po_number": null,
      "so_number": null
    }
  ],
  "ship_date_questions": [],
  "hold_questions": [],
  "other_questions": [],
  
  "pdf_data": {
    "document_type": "Purchase Order",
    "po_number": "PO-2025-001",
    "vendor": "ACME Corp",
    "items": [
      {
        "line": 1,
        "sku": "SKU-001",
        "description": "Widget A – Gold – 1 Inch",
        "quantity": 100,
        "unit_price": 10.50
      }
    ],
    "total": 1050.00,
    "notes": "Rush order"
  }
}

PO to SO Conversion

Trigger Phrases (from internal CSR)

✅ "create so from po"
✅ "convert this po to so"
✅ "enter this po as a sales order"
✅ "create sales order from this purchase order"

❌ Customer: "Please confirm the attached PO" → routes to ship_date
❌ Customer: "Here is our order" → routes to ship_date

What Happens

1. Classifier sets has_po2so: true
2. API runs PO2SO preview (matches PDF items to NetSuite items)
3. If items matched successfully, creates the Sales Order
4. Returns so_created with SO number

Response when SO is created

{
  "workflow": "po2so",
  "raw_data": {
    "customer": { "id": 12345, "name": "ACME Corp" },
    "so_created": {
      "id": 67890,
      "tranid": "SOSX25-12345"
    },
    "po_items": [
      {
        "original_sku": "SKU-001",
        "matched_item": { "itemid": "SKU-001-GOLD", "unit_price": 10.50 },
        "match_status": "matched"
      }
    ]
  },
  "summary": "Sales Order SOSX25-12345 created from PO PO-2025-001"
}

Endpoints

Main endpoint. Accepts classifier JSON output and routes to appropriate workflows. Handles all workflow types including po2so (which can write to NetSuite).

Direct PO to SO endpoint. Use create_so: true to create, create_so: false for preview only.

All Input Fields

Question Object Format

Each question in the arrays follows this structure:

{
  "index": 0,
  "normalized_question": "What is the price for SKU-001?",
  "source_quote": "can you send pricing for SKU-001?",
  "item_hints": ["SKU-001", "Widget"],
  "po_number": "PO-2025-001",
  "so_number": null
}

pdf_data Object Format

{
  "document_type": "Purchase Order",
  "po_number": "PO-2025-001",
  "vendor": "ACME Corp",
  "items": [
    {
      "line": 1,
      "sku": "SKU-001",
      "description": "Widget A – Gold – 1 Inch",
      "quantity": 100,
      "unit_price": 10.50
    }
  ],
  "total": 1050.00,
  "notes": "Rush order, ship by end of month"
}

API Response Format

{
  "ok": true,
  "customer_identity": {
    "email": "buyer@acmecorp.com",
    "name": "Jane Doe",
    "company": "ACME Corp"
  },
  "workflow_results": [
    {
      "workflow": "stock_price",
      "raw_data": {
        "customer": { "id": 12345, "name": "ACME Corporation" },
        "items": [
          {
            "itemid": "SKU-001-GOLD",
            "description": "Widget A Gold",
            "unit_price": 10.50,
            "on_hand": 500,
            "available": 450,
            "committed": 50
          }
        ],
        "notes": ["Found in customer history at $10.50"]
      },
      "summary": "Found 1 item(s)",
      "errors": []
    }
  ],
  "debug": {
    "request_id": "req_abc123",
    "model_used": "claude-3-5-haiku-20241022",
    "timings": { "stock_price": 5000, "total": 5000 }
  }
}

Error Codes

NetSuite MCP API v1.0