Customer Record API

Create, read, update, and delete customer records using the NetSuite REST API.

---

Endpoints

Method	Endpoint	Description
GET	/record/v1/customer	List all customers
GET	/record/v1/customer/{id}	Get specific customer
POST	/record/v1/customer	Create new customer
PATCH	/record/v1/customer/{id}	Update existing customer
DELETE	/record/v1/customer/{id}	Delete customer

Base URL

https://{account_id}.suitetalk.api.netsuite.com/services/rest/record/v1/customer

---

Key Fields

Identification & Basic Info

Field	Type	Description	Required
id	string	Internal ID (read-only)	-
entityId	string	Customer ID/Name	Yes (if not auto)
autoName	boolean	Auto-generate name	No
companyName	string	Company name	Yes (if company)
isPerson	boolean	Individual vs company	No
firstName	string	First name (if person)	Conditional
lastName	string	Last name (if person)	Conditional
subsidiary	object	Primary subsidiary	Yes (if OneWorld)

Contact Information

Field	Type	Description
email	string	Primary email address
altEmail	string	Alternate email
phone	string	Primary phone
altPhone	string	Alternate phone
fax	string	Fax number
url	string	Website URL

Financial Fields

Field	Type	Description
balance	number	Current A/R balance (read-only)
creditLimit	number	Maximum credit allowed
terms	object	Payment terms
currency	object	Customer currency
taxable	boolean	Subject to tax
taxItem	object	Default tax code

Classification & Segmentation

Field	Type	Description
category	object	Customer category
salesRep	object	Assigned sales representative
partner	object	Referral partner
department	object	Department
class	object	Classification
location	object	Location

Accounting Settings

Field	Type	Description
receivablesAccount	object	A/R account
billingSchedule	object	Recurring billing schedule
priceLevel	object	Default price level
discountItem	object	Automatic discount

Status & Dates

Field	Type	Description
entityStatus	object	Customer status
inactive	boolean	Inactive flag
dateCreated	string	Creation date (read-only)
lastModifiedDate	string	Last modified date (read-only)

Aging (Read-Only)

Field	Type	Description
aging	number	Current balance
aging1	number	1-30 days overdue
aging2	number	31-60 days overdue
aging3	number	61-90 days overdue
aging4	number	Over 90 days overdue

Sublists/Collections

Field	Type	Description
addressBook	collection	Customer addresses
contactRoles	collection	Associated contacts
creditCards	collection	Saved credit cards
currencyList	collection	Accepted currencies
itemPricing	collection	Custom item pricing

---

Example: Create Company Customer

POST /record/v1/customer
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "companyName": "Acme Corporation",
  "entityId": "ACME-001",
  "isPerson": false,
  "subsidiary": {
    "id": "1"
  },
  "email": "contact@acmecorp.com",
  "phone": "555-0100",
  "terms": {
    "id": "2"
  },
  "currency": {
    "id": "1"
  },
  "salesRep": {
    "id": "123"
  },
  "category": {
    "id": "1"
  },
  "taxable": true
}

Response

{
  "links": [
    {
      "rel": "self",
      "href": "https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customer/456"
    }
  ],
  "id": "456",
  "refName": "Acme Corporation",
  "entityId": "ACME-001",
  "companyName": "Acme Corporation",
  "isPerson": false,
  "email": "contact@acmecorp.com",
  "phone": "555-0100",
  "balance": 0,
  "dateCreated": "2025-12-25T10:00:00Z",
  "lastModifiedDate": "2025-12-25T10:00:00Z"
}

---

Example: Create Individual Customer

POST /record/v1/customer
Content-Type: application/json

{
  "isPerson": true,
  "entityId": "CUST-002",
  "firstName": "John",
  "lastName": "Smith",
  "subsidiary": {
    "id": "1"
  },
  "email": "john.smith@email.com",
  "phone": "555-0200",
  "terms": {
    "refName": "Net 30"
  },
  "currency": {
    "refName": "USA"
  }
}

---

Example: Update Customer

PATCH /record/v1/customer/456
Content-Type: application/json

{
  "email": "newemail@acmecorp.com",
  "phone": "555-0999",
  "creditLimit": 50000,
  "terms": {
    "id": "3"
  }
}

Partial Updates

With PATCH, only include fields you want to change. All other fields remain unchanged.

---

Example: Add Address (Sublist)

PATCH /record/v1/customer/456
Content-Type: application/json

{
  "addressBook": {
    "items": [
      {
        "defaultShipping": true,
        "defaultBilling": false,
        "label": "Main Office",
        "addressBookAddress": {
          "addr1": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102",
          "country": {
            "refName": "US"
          }
        }
      }
    ]
  }
}

---

Query Filters

Find Customers by Company Name

GET /record/v1/customer?q=companyName LIKE 'Acme%'

Find Customers by Email

GET /record/v1/customer?q=email='john.smith@email.com'

Find Inactive Customers

GET /record/v1/customer?q=inactive=true

Find Customers by Status

GET /record/v1/customer?q=entityStatus='13'

Find Customers with High Balance

GET /record/v1/customer?q=balance > 10000

---

Common Use Cases

1. Check Customer Credit Limit

const customer = await getCustomer(customerId);
if (customer.balance + orderTotal > customer.creditLimit) {
  // Require approval or payment
}

2. Update Customer After Payment

// NetSuite automatically updates balance
// Just retrieve to see current balance
const updated = await getCustomer(customerId);
console.log(`New balance: ${updated.balance}`);

3. Activate/Deactivate Customer

await patchCustomer(customerId, {
  inactive: true
});

4. Change Payment Terms

await patchCustomer(customerId, {
  terms: { id: "1" }  // Net 15
});

---

Important Notes

Required Fields

• OneWorld Accounts: subsidiary is required
• Company: companyName required if isPerson=false
• Individual: firstName and lastName required if isPerson=true
• Entity ID: Required unless autoName=true

Read-Only Fields

These fields are calculated by NetSuite and cannot be set via API:

• balance - Current A/R balance
• aging, aging1, aging2, aging3, aging4 - Aging buckets
• dateCreated, lastModifiedDate - System timestamps
• id - Internal ID

Reference Fields

Most reference fields accept either internal ID or display name:

{
  "terms": { "id": "2" }
}
// OR
{
  "terms": { "refName": "Net 30" }
}

Subsidiary Restrictions

In OneWorld accounts, you can only access customers in subsidiaries you have permission for.

---

Error Handling

Duplicate Customer

{
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title": "Conflict",
  "status": 409,
  "o:errorDetails": [
    {
      "detail": "A customer with this name already exists",
      "o:errorCode": "UNIQUE_CUST_ID_REQD"
    }
  ]
}

Solution: Use a different entityId or enable autoName.

Missing Required Field

{
  "status": 400,
  "o:errorDetails": [
    {
      "detail": "Please enter value(s) for: Company Name",
      "o:errorCode": "FIELD_REQUIRED"
    }
  ]
}

Solution: Ensure companyName is provided for company customers.

---

See Also

• Customer Category - Categorize customers
• Customer Status - Custom status values
• Contact - Associated contact records
• Sales Order - Create orders for customers
• Invoice - Bill customers