---
updatedAt: 2026-07-20T06:33:37.000Z
agentTools:
  projectIndex: https://docs.paymongo.com/llms.txt
---

# Update deal stage

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "contact": {
      "name": "Sales and Marketing Experience Team"
    },
    "description": "Sales API owns PayMongo's internal sales CRM: the organization/company\ncatalog, contacts, leads, deals and pipeline stages, sales activities and\ntrackers, notes, tags, tickets, and account invitations. Called by the\ninternal admin dashboard on behalf of authenticated PayMongo sales admins.\n",
    "title": "Sales API",
    "version": "1.0.0",
    "summary": "Internal sales CRM — organizations, contacts, leads, deals, pipelines, activities, and tickets.",
    "license": {
      "name": "PayMongo Internal",
      "identifier": "LicenseRef-PayMongo-Internal"
    },
    "x-paymongo-service-slug": "sales-api",
    "x-paymongo-service-tier": "tier-2",
    "x-paymongo-owner-slack": "#sales-api-channel",
    "x-paymongo-repo": "https://github.com/paymongo/sales-api",
    "x-paymongo-data-classification": "internal"
  },
  "servers": [
    {
      "url": "https://sales-api.paymongo.com",
      "description": "Production"
    },
    {
      "url": "https://sales-api.paymongo-uat.com",
      "description": "UAT"
    },
    {
      "url": "https://sales-api.paymongo-stg.com",
      "description": "Staging"
    }
  ],
  "tags": [
    {
      "name": "Deals",
      "description": "Deals and their lifecycle through pipeline stages."
    }
  ],
  "paths": {
    "/v1/internal/deals/{deal_id}/stage": {
      "patch": {
        "parameters": [
          {
            "description": "Deal ID",
            "example": "deal_0123456789abcdef01234567",
            "in": "path",
            "name": "deal_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDealStageReqDTO"
              }
            }
          },
          "description": "Stage",
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ResponseRootDTO"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/UpdateDealStageResDTO"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRootDTO"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRootDTO"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseRootDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update deal stage",
        "tags": [
          "Deals"
        ],
        "operationId": "update_internal_deals_deal_id_stage"
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorCode": {
        "enum": [
          "invalid_query_parameters",
          "invalid_request_body",
          "parameter_required",
          "not_found",
          "unauthorized",
          "internal_server_error"
        ],
        "type": "string",
        "x-enum-varnames": [
          "ErrInvalidQueryParameters",
          "ErrInvalidRequestBody",
          "ErrParameterRequired",
          "ErrNotFound",
          "ErrUnauthorized",
          "ErrInternalServerError"
        ]
      },
      "ErrorDetail": {
        "description": "Details about a specific error",
        "properties": {
          "code": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorCode"
              }
            ],
            "description": "Code is an application-specific error code, expressed as a string value.",
            "example": "invalid_request_body"
          },
          "detail": {
            "description": "Detail is a human-readable explanation specific to this occurrence of the problem.",
            "example": "Explanation of error code for this case",
            "type": "string"
          },
          "source": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Source"
              }
            ],
            "description": "Source is an object containing references to the primary source of the error"
          }
        },
        "type": "object"
      },
      "ErrorResponseRootDTO": {
        "description": "Standard error response containing one or more errors",
        "properties": {
          "errors": {
            "description": "Error objects MUST be returned as an array keyed by `errors` in the top level of a JSON:API document.",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ResponseRootDTO": {
        "properties": {
          "data": {}
        },
        "type": "object"
      },
      "Source": {
        "description": "Source of the error, providing context like JSON Pointer or query parameter",
        "properties": {
          "header": {
            "description": "Header indicates the name of a single request header which caused the error.",
            "example": "X-Header-Name",
            "type": "string"
          },
          "parameter": {
            "description": "Parameter indicates which URI query parameter caused the error.",
            "example": "field_name",
            "type": "string"
          },
          "pointer": {
            "description": "Pointer is a \"JSON Pointer\" [RFC6901] to the value in the request document that caused the error.",
            "example": "/data/customers/0/attributes/name",
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateDealStageReqDTO": {
        "properties": {
          "stage_id": {
            "example": "stg_0123456789abcdef01234567",
            "type": "string"
          }
        },
        "required": [
          "stage_id"
        ],
        "type": "object"
      },
      "UpdateDealStageResDTO": {
        "properties": {
          "business_group": {
            "type": "string"
          },
          "created_at": {
            "example": "2026-07-01 10:00:00+00:00",
            "type": "string"
          },
          "currency_code": {
            "type": "string"
          },
          "daily_incremental_gp": {
            "type": "number"
          },
          "expected_close_date": {
            "example": "2026-07-01 10:00:00+00:00",
            "type": "string"
          },
          "id": {
            "example": "deal_0123456789abcdef01234567",
            "type": "string"
          },
          "included_in_forecast": {
            "example": true,
            "type": "boolean"
          },
          "is_closed": {
            "example": true,
            "type": "boolean"
          },
          "is_won": {
            "example": true,
            "type": "boolean"
          },
          "monthly_incremental_gp": {
            "type": "number"
          },
          "monthly_incremental_tpv": {
            "type": "number"
          },
          "name": {
            "example": "Acme Corp",
            "type": "string"
          },
          "outcome": {
            "enum": [
              "open",
              "won",
              "lost"
            ],
            "example": "open",
            "type": "string"
          },
          "outreach_start_date": {
            "example": "2026-07-01 10:00:00+00:00",
            "type": "string"
          },
          "pipeline_id": {
            "example": "pipe_0123456789abcdef01234567",
            "type": "string"
          },
          "priority": {
            "example": "high",
            "type": "string"
          },
          "stage_id": {
            "example": "stg_0123456789abcdef01234567",
            "type": "string"
          },
          "updated_at": {
            "example": "2026-07-01 10:00:00+00:00",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Admin access token (JWT) for PayMongo internal dashboard users; admin-only operations require an admin_id claim."
      }
    }
  }
}
```