Skip to main content

Customer Status API

Define custom status values for customers (e.g., Lead, Prospect, Active, Inactive).

Endpoints​

MethodEndpointDescription
GET/record/v1/customerStatusList all customer statuses
GET/record/v1/customerStatus/{id}Get specific status
POST/record/v1/customerStatusCreate new status
PATCH/record/v1/customerStatus/{id}Update status
DELETE/record/v1/customerStatus/{id}Delete status

Base URL​

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

Key Fields​

FieldTypeDescriptionRequired
idstringInternal ID (read-only)-
namestringStatus nameYes
descriptionstringStatus descriptionNo
includeInLeadReportsbooleanShow in lead reportsNo
probabilitynumberConversion probability % (0-100)No
stageobjectCustomer stage referenceNo
isInactivebooleanInactive flagNo

Example: Create Customer Status​

POST /record/v1/customerStatus
Content-Type: application/json
Authorization: Bearer {access_token}
{
  "name": "Qualified Lead",
  "description": "Lead that meets qualification criteria",
  "stage": {
    "id": "LEAD"
  },
  "probability": 25,
  "includeInLeadReports": true,
  "isInactive": false
}

Response​

{
  "links": [
    {
      "rel": "self",
      "href": "https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customerStatus/15"
    }
  ],
  "id": "15",
  "name": "Qualified Lead",
  "description": "Lead that meets qualification criteria",
  "stage": {
    "id": "LEAD",
    "refName": "LEAD"
  },
  "probability": 25,
  "includeInLeadReports": true,
  "isInactive": false
}

Example: Update Probability​

PATCH /record/v1/customerStatus/15
Content-Type: application/json
Authorization: Bearer {access_token}
{
  "probability": 50,
  "description": "Updated qualification criteria"
}

Response​

{
  "links": [
    {
      "rel": "self",
      "href": "https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customerStatus/15"
    }
  ],
  "id": "15",
  "name": "Qualified Lead",
  "description": "Updated qualification criteria",
  "probability": 50,
  "includeInLeadReports": true,
  "isInactive": false
}

Query Filters​

List All Active Statuses​

GET /record/v1/customerStatus?q=isInactive=false

Find Status by Name​

GET /record/v1/customerStatus?q=name='Qualified Lead'

Find Statuses by Stage​

GET /record/v1/customerStatus?q=stage='LEAD'

Find High-Probability Statuses​

GET /record/v1/customerStatus?q=probability >= 75

Find Statuses Included in Lead Reports​

GET /record/v1/customerStatus?q=includeInLeadReports=true

Status Stages​

NetSuite supports the following customer stages:

Stage IDDescriptionTypical Use
LEADUnqualified leadInitial contact, not yet qualified
PROSPECTQualified prospectQualified opportunity, active sales process
CUSTOMERActive customerPaying customer
CLOSED_WONCustomer (closed won)Successfully closed deal
CLOSED_LOSTLost opportunityDeal lost to competitor or no decision

Common Use Cases​

1. Create Lead-to-Customer Pipeline​

Define statuses for each stage of your sales process:

// Lead Stage
await createStatus({
  name: "New Lead",
  stage: { id: "LEAD" },
  probability: 10,
  includeInLeadReports: true
});

await createStatus({
  name: "Qualified Lead",
  stage: { id: "LEAD" },
  probability: 25,
  includeInLeadReports: true
});

// Prospect Stage
await createStatus({
  name: "Demo Scheduled",
  stage: { id: "PROSPECT" },
  probability: 40
});

await createStatus({
  name: "Proposal Sent",
  stage: { id: "PROSPECT" },
  probability: 60
});

await createStatus({
  name: "Negotiation",
  stage: { id: "PROSPECT" },
  probability: 75
});

// Customer Stage
await createStatus({
  name: "Customer - Active",
  stage: { id: "CUSTOMER" },
  probability: 100
});

await createStatus({
  name: "Customer - Closed Won",
  stage: { id: "CLOSED_WON" },
  probability: 100
});

2. Update Customer Status​

await patchCustomer(customerId, {
  entityStatus: { id: "15" }  // Qualified Lead
});

3. Pipeline Reporting​

Query customers by status to build pipeline reports:

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

4. Probability-Based Forecasting​

Use probability field for weighted pipeline forecasting:

const prospects = await getCustomers("stage='PROSPECT'");
const weightedPipeline = prospects.reduce((sum, customer) => {
  return sum + (customer.estimatedValue * customer.entityStatus.probability / 100);
}, 0);

Important Notes​

Required Fields​

  • name: Status name is required and should be unique
  • Other fields are optional and depend on your sales process

Stage vs Status​

  • Stage: High-level category (LEAD, PROSPECT, CUSTOMER)
  • Status: Detailed state within a stage (Qualified Lead, Demo Scheduled, etc.)
  • One stage can have multiple statuses

Probability Field​

  • Represents the likelihood of conversion to customer (0-100%)
  • Used for weighted pipeline forecasting
  • Typically increases as prospect moves through stages
  • Customer stage statuses typically have 100% probability

Lead Reports​

  • Setting includeInLeadReports=true includes customers with this status in lead reports
  • Typically enabled for LEAD and PROSPECT stage statuses
  • Disabled for CUSTOMER stage statuses

System Default Statuses​

NetSuite includes several default statuses:

  • LEAD-Unqualified
  • PROSPECT-In Discussion
  • CUSTOMER-Closed Won
  • These can be customized but not deleted

Deleting Statuses​

  • Cannot delete statuses assigned to active customers
  • Cannot delete system default statuses
  • Mark as inactive instead if no longer needed

Best Practices​

  • Create statuses that match your actual sales process
  • Use consistent probability increments (e.g., 10%, 25%, 50%, 75%, 100%)
  • Include clear descriptions for sales team guidance
  • Review and update probabilities based on historical conversion rates
  • Align status names with CRM terminology your team uses

Example Sales Process Status Configuration​

B2B SaaS Company​

// Lead Stage (10-25%)
"Marketing Qualified Lead" - 10%
"Sales Qualified Lead" - 25%

// Prospect Stage (40-75%)
"Discovery Call Scheduled" - 40%
"Demo Completed" - 50%
"Proposal Sent" - 60%
"Negotiation" - 75%

// Customer Stage (100%)
"Customer - Active" - 100%
"Customer - Churned" - 0%

// Closed Lost (0%)
"Closed Lost - Competitor" - 0%
"Closed Lost - No Budget" - 0%
"Closed Lost - No Decision" - 0%

B2C Retail​

// Lead Stage
"Website Visitor" - 5%
"Email Subscriber" - 15%

// Prospect Stage
"Cart Abandoned" - 30%
"First Purchase Intent" - 50%

// Customer Stage
"One-Time Customer" - 100%
"Repeat Customer" - 100%
"VIP Customer" - 100%

See Also​