Deals

Deals represent sales opportunities. Each deal has a monetary value, belongs to a pipeline stage, and can be linked to contacts and companies.

Data Model

Field	Type	Description
`id`	`string`	Unique ID with `dl_` prefix
`title`	`string`	Deal name (required, max 300 chars)
`value`	`string \| null`	Monetary value as string for precision (e.g., `"50000.00"`)
`currency`	`string`	3-letter currency code (default: `EUR`)
`pipeline_id`	`string`	Pipeline this deal belongs to (`pp_` prefix)
`stage_id`	`string`	Current stage in the pipeline (`ps_` prefix)
`contact_id`	`string \| null`	Associated contact (`ct_` prefix)
`company_id`	`string \| null`	Associated company (`co_` prefix)
`owner_id`	`string \| null`	Deal owner
`expected_close_date`	`string \| null`	Expected close date (ISO 8601 date)
`closed_at`	`string \| null`	When the deal was closed (auto-set)
`custom_fields`	`object`	Custom field key-value pairs
`tags`	`string[]`	Tags for categorization
`created_at`	`string`	ISO 8601 timestamp
`updated_at`	`string`	ISO 8601 timestamp

Create a Deal

curl -X POST https://api.nodestash.io/v1/deals \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme Corp Enterprise License",
    "value": 50000,
    "currency": "EUR",
    "pipeline_id": "pp_abc123",
    "stage_id": "ps_def456",
    "contact_id": "ct_ghi789",
    "company_id": "co_jkl012",
    "expected_close_date": "2026-06-30",
    "tags": ["enterprise"]
  }'

const deal = await client.deals.create({
  title: 'Acme Corp Enterprise License',
  value: 50000,
  currency: 'EUR',
  pipeline_id: 'pp_abc123',
  stage_id: 'ps_def456',
  contact_id: 'ct_ghi789',
  company_id: 'co_jkl012',
  expected_close_date: '2026-06-30',
  tags: ['enterprise'],
})

Stage Progression

Move a deal through pipeline stages by updating stage_id:

curl -X PATCH https://api.nodestash.io/v1/deals/dl_abc123 \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "ps_won_stage"
  }'

await client.deals.update('dl_abc123', {
  stage_id: 'ps_won_stage',
})

When a deal moves to a won or lost stage, closed_at is automatically set to the current timestamp. Moving it back to an open stage clears closed_at.

Filter and Sort Deals

# Deals in a specific pipeline
curl "https://api.nodestash.io/v1/deals?pipeline_id=pp_abc123&sort=-value" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

# Deals by value range
curl "https://api.nodestash.io/v1/deals?min_value=10000&max_value=100000" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

// Deals in a pipeline, sorted by value
const { data } = await client.deals.list({
  pipeline_id: 'pp_abc123',
  sort: '-value',
})

// High-value deals
for await (const deal of client.deals.listAll({
  min_value: '10000',
  max_value: '100000',
})) {
  console.log(`${deal.title}: ${deal.value} ${deal.currency}`)
}

Available Filters

Parameter	Match Type	Description
`pipeline_id`	Exact	Filter by pipeline
`stage_id`	Exact	Filter by stage
`contact_id`	Exact	Filter by associated contact
`company_id`	Exact	Filter by associated company
`tags`	All match	Comma-separated, must have all
`min_value`	Range	Minimum deal value
`max_value`	Range	Maximum deal value