Opportunities

Change stage

Moves the opportunity to another stage. Stage gates apply exactly like in the web app: an unmet rule returns 409 gate with gate_problems. Send reason for Lost / Cancel. A won opportunity turns the company into a customer and emits opp_won to apps.

POST/api/v1/opportunities/{id}/stage

Authorization

Authorizationheaderrequired

Bearer token: API key (sk_…), OAuth access token (mcp_…) or mobile session (xk_…).

Module: OpportunitiesScope: crm.write

Path parameters

idintegerrequired

Opportunity id.

Body application/json

stagestringrequired

Target stage key (/me → constants.stages; closing keys are Win, Lost, Cancel).

notestringoptional

Note for the stage log.

reasonstringoptional

Loss / cancel reason (/me → constants.loss_reasons).

Errors

HTTP	error	Meaning
`400`	`invalid`	Missing or invalid field (`message` explains).
`403`	`forbidden`	You may not see / edit this record.
`404`	`not_found`	Record not found.
`409`	`gate`	Stage gate not met (`gate_problems`).

Request

curl -X POST https://ornek.solk.app/api/v1/opportunities/53/stage \
  -H "Authorization: Bearer $SOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "stage": "Viable",
  "note": "İhtiyaç ve bütçe doğrulandı."
}'

const res = await fetch("https://ornek.solk.app/api/v1/opportunities/53/stage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOLK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "stage": "Viable",
    "note": "İhtiyaç ve bütçe doğrulandı."
  }),
});
const data = await res.json();

import os, requests

r = requests.post(
    "https://ornek.solk.app/api/v1/opportunities/53/stage",
    headers={"Authorization": f"Bearer {os.environ['SOLK_API_KEY']}"},
    json={
        "stage": "Viable",
        "note": "İhtiyaç ve bütçe doğrulandı."
    },
)
print(r.json())

Response

{
  "messages": [
    "Aşama güncellendi: Viable"
  ],
  "ok": true,
  "opp": {
    "bant": 4,
    "bant_a": true,
    "bant_b": true,
    "bant_n": true,
    "bant_t": true,
    "base_currency": "EUR",
    "can_edit": true,
    "can_revive": false,
    "close_category": "",
    "close_date": "2026-11-16",
    "close_reason": "",
    "closed_at": null,
    "competitor": "Mevcut tedarikçi",
    "cur_sym": "€",
    "currency": "EUR",
    "customer": "Kuzey Plastik Sanayi",
    "customer_city": "Bursa",
    "customer_id": 31,
    "days_in_stage": 0,
    "demos": [],
    "detail_status": "",
    "fc": "Best Case",
    "gate_ok": false,
    "gate_problems": [
      "En az bir F2F ziyaret kaydı gerekir (Hızlı Giriş → tür F2F)"
    ],
    "guide": "f2f ziyaret + doğru ürün",
    "health": {
      "grade": "success",
      "label": "sağlıklı",
      "score": 80
    },
    "health_color": "g",
    "health_manual": false,
    "health_note": "",
    "health_why": [
      [
        "−15"
      ]
    ],
    "id": 53,
    "initials": "KP",
    "is_account": false,
    "is_open": true,
    "last_update": "2026-10-02",
    "lifetime_left": 180,
    "line": "",
    "logs": [
      {
        "date": "2026-10-02T20:07:00",
        "from": "Qualify",
        "note": "İhtiyaç ve bütçe doğrulandı.",
        "to": "Viable",
        "user": "Deniz Aksoy"
      }
    ],
    "name": "Streç film tedariki",
    "next_stage": "Present Solution",
    "next_step": "F2F ziyaret planla ve gerçekleştir",
    "note": "Numune onayı bekleniyor.",
    "notes": [],
    "offer_price": 2.35,
    "offers": [],
    "orders": [],
    "owner": {
      "full_name": "Deniz Aksoy",
      "id": 1,
      "role": "admin",
      "role_label": "Yönetici",
      "username": "admin"
    },
    "payment_days": 60,
    "potential_kg": 12000.0,
    "prob": 0.25,
    "probability": null,
    "product": "",
    "product_id": null,
    "pu": "€/kg",
    "rid": "006BMHmVNZ9nFLS",
    "sla_days": 60,
    "sla_left": 60,
    "source": "",
    "stage": "Viable",
    "stage_label": "Viable",
    "start_date": "2026-10-02",
    "steps": [
      {
        "assignee": {
          "full_name": "Deniz Aksoy",
          "id": 1,
          "role": "admin",
          "role_label": "Yönetici",
          "username": "admin"
        },
        "auto": true,
        "done": true,
        "due_date": null,
        "id": 467,
        "note": "otomatik: BANT kutusu",
        "stage": "Qualify",
        "state": "done",
        "title": "Karar verici / yetkili kişiyi belirle (Authority)"
      }
    ],
    "tags": [],
    "tasks": [],
    "threads": [],
    "threads_n": 0,
    "trend": "",
    "trend_label": "Otomatik",
    "type": "",
    "unit": "kg",
    "unit_code": "kg",
    "value": 338400.0,
    "value_base": 338400.0,
    "value_short": "338K",
    "visits": [],
    "weighted": 84600.0
  }
}

{
  "error": "gate",
  "gate_problems": [
    "BANT kriterleri 4/4 sağlanmalı (Budget · Authority · Need · Time)"
  ],
  "message": "Viable'a geçmek için: BANT kriterleri 4/4 sağlanmalı (Budget · Authority · Need · Time)",
  "ok": false
}

Example responses were captured from a v22 installation running sample data; lists are shortened to two items.