netsuite.yaml

Of course. Here is an OpenAPI 3.0 specification for the NetSuite SuiteTalk REST API, focusing on the most relevant endpoints for common business operations like managing customers, sales orders, invoices, and inventory.

This specification is structured to be used for building an MCP (Master Control Program) or any other integration client. It includes detailed schemas for core records, reusable parameters, and security definitions.

Generated yaml
openapi: 3.0.3
info:
  title: NetSuite SuiteTalk REST API
  description: An OpenAPI specification for NetSuite's SuiteTalk REST API, focusing on the most relevant endpoints for creating an MCP server. This covers core business records like Customer, Sales Order, Invoice, and Inventory Item.
  version: "1.0.0"
servers:
  - url: https://{accountId}.suitetalk.api.netsuite.com/services/rest/record/v1
    variables:
      accountId:
        default: "123456"
        description: Your NetSuite Account ID.
tags:
  - name: Customer
    description: Operations related to Customer records.
  - name: SalesOrder
    description: Operations related to Sales Order records.
  - name: Invoice
    description: Operations related to Invoice records.
  - name: InventoryItem
    description: Operations related to Inventory Item records.
  - name: PurchaseOrder
    description: Operations related to Purchase Order records.
  - name: Vendor
    description: Operations related to Vendor records.

paths:
  /customer:
    get:
      tags:
        - Customer
      summary: Get a list of Customers
      description: Retrieves a list of customer records, with support for filtering and pagination.
      operationId: getCustomers
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/preferHeader'
      responses:
        '200':
          description: A collection of customer records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerCollection'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
        - Customer
      summary: Create a new Customer
      description: Creates a new customer record.
      operationId: createCustomer
      parameters:
        - $ref: '#/components/parameters/preferHeader'
        - $ref: '#/components/parameters/replaceQuery'
        - $ref: '#/components/parameters/propertyNameValidationHeader'
        - $ref: '#/components/parameters/propertyValueValidationHeader'
      requestBody:
        description: Customer object to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer'
      responses:
        '204':
          description: Customer created successfully.
        default:
          $ref: '#/components/responses/DefaultError'

  /customer/{id}:
    parameters:
      - $ref: '#/components/parameters/idPath'
    get:
      tags:
        - Customer
      summary: Get a Customer by ID
      description: Retrieves a single customer record by its internal ID.
      operationId: getCustomerById
      parameters:
        - $ref: '#/components/parameters/expandSubResourcesQuery'
        - $ref: '#/components/parameters/fieldsQuery'
      responses:
        '200':
          description: Retrieved customer record successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
        - Customer
      summary: Update a Customer
      description: Updates an existing customer record.
      operationId: updateCustomer
      parameters:
        - $ref: '#/components/parameters/replaceQuery'
        - $ref: '#/components/parameters/replaceSelectedFieldsQuery'
        - $ref: '#/components/parameters/propertyNameValidationHeader'
        - $ref: '#/components/parameters/propertyValueValidationHeader'
      requestBody:
        description: The fields of the customer to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer'
      responses:
        '204':
          description: Customer updated successfully.
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      tags:
        - Customer
      summary: Delete a Customer
      description: Deletes a customer record by its internal ID.
      operationId: deleteCustomer
      responses:
        '204':
          description: Customer deleted successfully.
        default:
          $ref: '#/components/responses/DefaultError'

  /salesOrder:
    get:
      tags:
        - SalesOrder
      summary: Get a list of Sales Orders
      operationId: getSalesOrders
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A collection of sales order records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/salesOrderCollection'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
        - SalesOrder
      summary: Create a new Sales Order
      operationId: createSalesOrder
      requestBody:
        description: Sales Order object to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/salesOrder'
      responses:
        '204':
          description: Sales Order created successfully.
        default:
          $ref: '#/components/responses/DefaultError'

  /salesOrder/{id}:
    parameters:
      - $ref: '#/components/parameters/idPath'
    get:
      tags:
        - SalesOrder
      summary: Get a Sales Order by ID
      operationId: getSalesOrderById
      parameters:
        - $ref: '#/components/parameters/expandSubResourcesQuery'
      responses:
        '200':
          description: Retrieved sales order record successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/salesOrder'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
        - SalesOrder
      summary: Update a Sales Order
      operationId: updateSalesOrder
      requestBody:
        description: The fields of the sales order to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/salesOrder'
      responses:
        '204':
          description: Sales Order updated successfully.
        default:
          $ref: '#/components/responses/DefaultError'

  '/salesOrder/{id}/!transform/invoice':
    parameters:
      - $ref: '#/components/parameters/idPath'
    post:
      tags:
        - SalesOrder
      summary: Transform a Sales Order to an Invoice
      description: Creates an invoice from an existing sales order. The request body can contain values to override the defaults from the sales order.
      operationId: transformSalesOrderToInvoice
      requestBody:
        description: Invoice data to override defaults from the source sales order.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/invoice'
      responses:
        '200':
          description: Transformed record returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invoice'
        default:
          $ref: '#/components/responses/DefaultError'

  /invoice:
    get:
      tags:
        - Invoice
      summary: Get a list of Invoices
      operationId: getInvoices
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A collection of invoice records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invoiceCollection'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
        - Invoice
      summary: Create a new Invoice
      operationId: createInvoice
      requestBody:
        description: Invoice object to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/invoice'
      responses:
        '204':
          description: Invoice created successfully.
        default:
          $ref: '#/components/responses/DefaultError'

  /invoice/{id}:
    parameters:
      - $ref: '#/components/parameters/idPath'
    get:
      tags:
        - Invoice
      summary: Get an Invoice by ID
      operationId: getInvoiceById
      parameters:
        - $ref: '#/components/parameters/expandSubResourcesQuery'
      responses:
        '200':
          description: Retrieved invoice record successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invoice'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
        - Invoice
      summary: Update an Invoice
      operationId: updateInvoice
      requestBody:
        description: The fields of the invoice to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/invoice'
      responses:
        '204':
          description: Invoice updated successfully.
        default:
          $ref: '#/components/responses/DefaultError'
  
  # Add other relevant paths like /vendor, /purchaseOrder, /inventoryItem following the same pattern...

components:
  parameters:
    idPath:
      name: id
      in: path
      description: Internal identifier of the record.
      required: true
      schema:
        type: integer
        format: int32
    query:
      name: q
      in: query
      description: The search query that is used to filter results using SuiteQL.
      required: false
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: The limit used to specify the number of results on a single page.
      required: false
      schema:
        type: integer
        format: int32
        default: 1000
    offset:
      name: offset
      in: query
      description: The offset used for selecting a specific page of results.
      required: false
      schema:
        type: integer
        format: int32
        default: 0
    preferHeader:
      name: Prefer
      in: header
      description: "Use 'respond-async' to execute the request asynchronously."
      required: false
      schema:
        type: string
        enum: [respond-async]
    propertyNameValidationHeader:
      name: X-NetSuite-PropertyNameValidation
      in: header
      description: Sets the strictness of property name validation.
      required: false
      schema:
        type: string
        enum: [Error, Warning, Ignore]
        default: Warning
    propertyValueValidationHeader:
      name: X-NetSuite-PropertyValueValidation
      in: header
      description: Sets the strictness of property value validation.
      required: false
      schema:
        type: string
        enum: [Error, Warning, Ignore]
        default: Error
    replaceQuery:
      name: replace
      in: query
      description: Comma-delimited names of sublists to replace entirely with the lines from the request.
      required: false
      schema:
        type: string
    replaceSelectedFieldsQuery:
      name: replaceSelectedFields
      in: query
      description: If true, all fields to be deleted in an update request must be included in the 'replace' query parameter.
      required: false
      schema:
        type: boolean
        default: false
    expandSubResourcesQuery:
      name: expandSubResources
      in: query
      description: Set to 'true' to automatically expand all sublists, sublist lines, and subrecords.
      required: false
      schema:
        type: boolean
        default: false
    fieldsQuery:
      name: fields
      in: query
      description: Comma-delimited names of fields and sublists to return in the response.
      required: false
      schema:
        type: string

  responses:
    DefaultError:
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/nsError'

  schemas:
    nsError:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
        o:errorDetails:
          type: array
          items:
            type: object
            properties:
              detail:
                type: string
                description: A human-readable explanation specific to this occurrence of the problem.
              o:errorCode:
                type: string
                description: A machine-readable error code.
    nsLink:
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
          format: uri
        
    nsRef:
      type: object
      description: A reference to another NetSuite resource.
      properties:
        id:
          type: string
          description: The internal ID of the referenced resource.
        refName:
          type: string
          description: The reference name of the resource.
        links:
          type: array
          items:
            $ref: '#/components/schemas/nsLink'

    # Customer Schemas
    customer:
      type: object
      properties:
        id:
          type: string
          description: Internal ID of the customer.
          readOnly: true
        entityId:
          type: string
          description: The customer's ID or name, depending on auto-numbering settings.
        companyName:
          type: string
          description: The legal name of the company.
        isPerson:
          type: boolean
          description: True if the customer is an individual, false if it's a company.
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        subsidiary:
          $ref: '#/components/schemas/nsRef'
        category:
          $ref: '#/components/schemas/nsRef'
        creditLimit:
          type: number
          format: double
        terms:
          $ref: '#/components/schemas/nsRef'
        isInactive:
          type: boolean
          default: false
        addressBook:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/customerAddress'
    
    customerAddress:
      type: object
      properties:
        defaultShipping:
          type: boolean
        defaultBilling:
          type: boolean
        label:
          type: string
        addressBookAddress:
          type: object
          properties:
            country:
              type: string
              description: 2-letter country code (e.g., US, CA).
            addressee:
              type: string
            addr1:
              type: string
            city:
              type: string
            state:
              type: string
            zip:
              type: string

    customerCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/customer'
        count:
          type: integer
        hasMore:
          type: boolean
        offset:
          type: integer
        totalResults:
          type: integer
    
    # Sales Order Schemas
    salesOrder:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        createdFrom:
          $ref: '#/components/schemas/nsRef'
        entity:
          $ref: '#/components/schemas/nsRef'
          description: Reference to the customer.
        tranDate:
          type: string
          format: date
          description: The date of the sales order.
        orderStatus:
          type: string
          readOnly: true
        subsidiary:
          $ref: '#/components/schemas/nsRef'
        location:
          $ref: '#/components/schemas/nsRef'
        memo:
          type: string
        item:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/transactionLine'

    salesOrderCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/salesOrder'
        # ... pagination properties
    
    # Invoice Schemas
    invoice:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        createdFrom:
          $ref: '#/components/schemas/nsRef'
          description: Reference to the Sales Order this invoice was created from.
        entity:
          $ref: '#/components/schemas/nsRef'
          description: Reference to the customer.
        tranDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        subsidiary:
          $ref: '#/components/schemas/nsRef'
        location:
          $ref: '#/components/schemas/nsRef'
        status:
          type: string
          readOnly: true
        total:
          type: number
          format: double
          readOnly: true
        item:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/transactionLine'

    invoiceCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/invoice'
        # ... pagination properties
        
    # Common Transaction Line Schema
    transactionLine:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/nsRef'
        quantity:
          type: number
          format: double
        rate:
          type: number
          format: double
        amount:
          type: number
          format: double
        description:
          type: string
        taxCode:
          $ref: '#/components/schemas/nsRef'
        location:
          $ref: '#/components/schemas/nsRef'
          
  securitySchemes:
    # NetSuite uses a custom HMAC-SHA256 signature, which doesn't map perfectly.
    # We represent it as a set of API keys passed in the Authorization header.
    # A more common alternative for modern APIs is OAuth 2.0.
    tba:
      type: apiKey
      in: header
      name: Authorization
      description: Token-Based Authentication. The header value is complex and must be constructed with a signature. Example format `Authorization: NLAuth nlauth_account=12345, nlauth_consumer_key=..., nlauth_token=..., nlauth_signature_method="HMAC-SHA256", nlauth_signature=...`
    oauth2:
      type: oauth2
      description: OAuth 2.0 for authenticating with the NetSuite API.
      flows:
        authorizationCode:
          authorizationUrl: https://{accountId}.app.netsuite.com/app/login/oauth2/authorize.nl
          tokenUrl: https://{accountId}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token
          scopes:
            rest_webservices: Access to REST Web Services
            restlets: Access to RESTlets

security:
  - tba: []
  - oauth2:
    - rest_webservices