Pipeline Stages

Pipeline stages represent the steps in your sales process. Each stage belongs to a specific pipeline and contains deals that are at that point in the workflow. Stages track metrics like deal count, total amount, probability, and rotting days.

The Pipeline Stage Object

  • Name
    id
    Type
    uuid
    Description

    Unique identifier for the stage.

  • Name
    pipeline_id
    Type
    uuid
    Description

    The pipeline this stage belongs to.

  • Name
    sort
    Type
    integer
    Description

    Sort order within the pipeline (starts at 1).

  • Name
    name
    Type
    string
    Description

    Stage name (max 255 characters).

  • Name
    probability
    Type
    integer
    Description

    Win probability percentage (0-100). Default is 100.

  • Name
    rotting_days
    Type
    integer
    Description

    Number of days before deals in this stage are considered stale. Default is 0 (no rotting).

  • Name
    total_deals
    Type
    integer
    Description

    Total number of deals currently in this stage.

  • Name
    total_deals_amount
    Type
    integer
    Description

    Sum of all deal amounts in this stage (in cents).

  • Name
    total_deals_amount_formatted
    Type
    string
    Description

    Formatted total deal amount with currency symbol (e.g., $50,000.00).

  • Name
    created_at
    Type
    datetime
    Description

    Timestamp when the stage was created.

  • Name
    updated_at
    Type
    datetime
    Description

    Timestamp when the stage was last updated.

POST/app/pipelines/{id}/stages

Create a Pipeline Stage

Create a new stage within a pipeline. The stage will be automatically sorted at the end of the current stage list with default probability of 100 and rotting_days of 0.

Required Attributes

  • Name
    name
    Type
    string
    Required
    *
    Description

    Stage name (max 255 characters).

Request

POST
/app/pipelines/{id}/stages
curl -X POST https://api.pipeback.com/app/pipelines/9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a/stages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract Negotiation"
  }'

Response

{
  "data": {
    "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3c",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "sort": 3,
    "name": "Contract Negotiation",
    "probability": 100,
    "rotting_days": 0,
    "total_deals": 0,
    "total_deals_amount": 0,
    "total_deals_amount_formatted": "$0.00",
    "created_at": "2025-10-26 16:00:00",
    "updated_at": "2025-10-26 16:00:00"
  }
}
PUT/app/pipelines/{id}/stages/{stageId}

Update a Pipeline Stage

Update an existing pipeline stage's name.

Required Attributes

  • Name
    name
    Type
    string
    Required
    *
    Description

    Stage name (max 255 characters).

Request

PUT
/app/pipelines/{id}/stages/{stageId}
curl -X PUT https://api.pipeback.com/app/pipelines/9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a/stages/9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3c \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Final Negotiations"
  }'

Response

{
  "data": {
    "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3c",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "sort": 3,
    "name": "Final Negotiations",
    "probability": 100,
    "rotting_days": 0,
    "total_deals": 0,
    "total_deals_amount": 0,
    "total_deals_amount_formatted": "$0.00",
    "created_at": "2025-10-26 16:00:00",
    "updated_at": "2025-10-26 16:15:00"
  }
}
DELETE/app/pipelines/{id}/stages/{stageId}

Delete a Pipeline Stage

Delete a stage from a pipeline. This performs a soft delete, preserving the stage data but marking it as deleted.

You cannot delete stages from the default pipeline. Attempting to do so will result in a 400 error. Deals in the deleted stage will remain in the database but should be moved to another stage before deletion.

Request

DELETE
/app/pipelines/{id}/stages/{stageId}
curl -X DELETE https://api.pipeback.com/app/pipelines/9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a/stages/9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3c \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
}

Error Response (Default Pipeline)

{
  "status": "error",
  "message": "You cannot delete the default pipeline."
}

Stage Metrics

Each pipeline stage includes aggregated deal metrics:

  • total_deals: Count of all deals currently in this stage
  • total_deals_amount: Sum of deal amounts in cents (e.g., 5000000 = $50,000.00)
  • total_deals_amount_formatted: Human-readable formatted amount with currency symbol

These metrics are calculated in real-time when retrieving stage data and reflect the current state of deals in the stage.

Probability and Rotting

Pipeline stages have two configurable properties for deal management:

Probability

The probability field represents the expected win rate for deals at this stage (0-100%). This helps forecast revenue based on deal stage. Default value is 100.

  • Early stages: Lower probability (e.g., 10-25%)
  • Mid stages: Medium probability (e.g., 50-75%)
  • Late stages: High probability (e.g., 90-100%)

Rotting Days

The rotting_days field defines how many days a deal can remain in this stage before being flagged as stale or "rotting". Default value is 0 (no rotting).

  • 0: No rotting detection
  • 7-14 days: Active sales stages
  • 30+ days: Later stages like contract negotiation

This helps identify deals that need attention and prevents pipeline stagnation.

Default Pipeline Protection

Stages in the default pipeline have special protection:

  • You cannot delete stages from the default pipeline
  • This prevents accidental removal of critical workflow stages
  • If you need to delete a stage, first set another pipeline as default
  • Attempting to delete a default pipeline stage returns a 400 error

This ensures your primary sales workflow remains stable and consistent.

Something wrong with this page?