Pipelines
Define sales processes with custom pipelines and stages
Pipelines define the stages a deal moves through in your sales process. Each pipeline contains ordered stages of type open, won, or lost.
Data Model
Pipeline
| Field | Type | Description |
|---|---|---|
id | string | Unique ID with pp_ prefix |
name | string | Pipeline name (required, max 200 chars) |
description | string | null | Description (max 1000 chars) |
is_default | boolean | Whether this is the default pipeline |
stages | PipelineStage[] | Ordered list of stages |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Pipeline Stage
| Field | Type | Description |
|---|---|---|
id | string | Unique ID with ps_ prefix |
name | string | Stage name (max 100 chars) |
position | integer | Order position (starting from 0) |
type | string | open, won, or lost |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Stage Types
Each stage has a type that affects deal behavior:
| Type | Description |
|---|---|
open | Active deal stage — deal is still in progress |
won | Win stage — moving a deal here auto-sets closed_at |
lost | Loss stage — moving a deal here auto-sets closed_at |
Every pipeline must have at least one won stage and at least one lost stage.
Create a Pipeline
Create a pipeline with its initial stages in a single request:
curl -X POST https://api.nodestash.io/v1/pipelines \
-H "Authorization: Bearer $NODESTASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Enterprise Sales",
"description": "Pipeline for enterprise deals over 10K",
"stages": [
{ "name": "Qualification", "position": 0, "type": "open" },
{ "name": "Discovery", "position": 1, "type": "open" },
{ "name": "Proposal", "position": 2, "type": "open" },
{ "name": "Negotiation", "position": 3, "type": "open" },
{ "name": "Closed Won", "position": 4, "type": "won" },
{ "name": "Closed Lost", "position": 5, "type": "lost" }
]
}'const pipeline = await client.pipelines.create({
name: 'Enterprise Sales',
description: 'Pipeline for enterprise deals over 10K',
stages: [
{ name: 'Qualification', position: 0, type: 'open' },
{ name: 'Discovery', position: 1, type: 'open' },
{ name: 'Proposal', position: 2, type: 'open' },
{ name: 'Negotiation', position: 3, type: 'open' },
{ name: 'Closed Won', position: 4, type: 'won' },
{ name: 'Closed Lost', position: 5, type: 'lost' },
],
})Manage Stages
Add, update, or remove stages after pipeline creation:
Add a Stage
curl -X POST https://api.nodestash.io/v1/pipelines/pp_abc123/stages \
-H "Authorization: Bearer $NODESTASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Contract Review",
"position": 3,
"type": "open"
}'const stage = await client.pipelines.stages.create('pp_abc123', {
name: 'Contract Review',
position: 3,
type: 'open',
})Update a Stage
curl -X PATCH https://api.nodestash.io/v1/pipelines/pp_abc123/stages/ps_def456 \
-H "Authorization: Bearer $NODESTASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Legal Review"
}'await client.pipelines.stages.update('pp_abc123', 'ps_def456', {
name: 'Legal Review',
})Delete a Stage
curl -X DELETE https://api.nodestash.io/v1/pipelines/pp_abc123/stages/ps_def456 \
-H "Authorization: Bearer $NODESTASH_API_KEY"await client.pipelines.stages.delete('pp_abc123', 'ps_def456')