SoftSolzSoftSolz
Sign up
HomeAPI GuideAPI ReferenceWidget Tester
Sales Pipelines

Update or move a deal

Send only the fields you want to change. Send stage_id to move the deal, on its own or with other fields (the fields are saved first, then the deal moves): it goes to the end of that stage, its status follows the stage, and the stage may require some deal fields to be filled first. Moving to a won or lost stage closes the deal and stamps closed_at with that time; moving it back to a working stage reopens it and clears closed_at and any lost reason. Send lost_reason (text) or lost_reason_id when moving to a lost stage, or afterwards while the deal is lost; a reason on a deal that is not lost is refused with 409 deal_not_lost. A field that is not listed here is refused with 400 unknown_field. Send expected_updated_at (the updated_at you last read) to be refused with 409 when somebody else changed the deal first. A deal that is not on the board in the address answers 404 deal_not_found.

PATCHhttps://app.softsolz.uk/api/v1/services/pipelines/pipelines/{pipeline_id}/deals/{deal_id}

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Path Params

pipeline_idstringrequired
deal_idstringrequired

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Body Params

titlestring

Deal name, up to 200 characters. Longer text is refused with 400 title_too_long.

value_centsinteger

Deal value in minor units (pence or cents), a whole number of zero or more. A negative, fractional or non-numeric value is refused with 400 invalid_value. While the deal has line items its value is the sum of the lines, and sending a different value is refused with 400 value_set_by_lines.

currencystring

Three-letter currency code. Leave out to use the board currency, or the workspace currency when the board has none.

owner_user_idinteger | null

Workspace member who owns the deal. Must be an active member of the workspace; null leaves it unassigned.

contact_idstring | null

Contact the deal is with. Must be a contact in this workspace. When the contact belongs to a company and company_id is not sent, the deal is linked to that company too.

company_idstring | null

Company the deal is with. Must be a company in this workspace.

expected_close_onstring | null

Expected close date as a plain YYYY-MM-DD date. Anything else is refused with 400 invalid_close_date. The forecast places the deal in this period.

sourcestring | null

Where the deal came from, up to 120 characters.

notesstring | null

Free-text notes, up to 2000 characters.

lost_reasonstring | null

Free-text reason the deal was lost. When it matches a reason on the workspace list (ignoring capitals) that reason is linked and lost_reason_id is set; otherwise the text is kept as written. Send null to clear it.

lost_reason_idstring | null

Id of a reason on the workspace lost-reason list. An unknown id is refused with 404 lost_reason_not_found. Send null to clear it.

expected_updated_atstring

The updated_at you last read for this deal. When the deal has changed since, the update is refused with 409 and nothing is saved.

stage_idstring

Stage to move the deal to. Must be a stage on the deal board. Send it on its own or together with the other fields.

Response

Response Body

idstringDeal id.
pipeline_idstringBoard the deal sits on.
stage_idstringStage the deal is in.
stage_namestring | nullName of that stage.
titlestringDeal name.
value_centsintegerDeal value in minor units (pence or cents).
value_from_linesbooleanTrue while the deal has line items. The value is then the sum of the lines and cannot be set directly; removing the last line restores the value the deal had before lines were added, or 0.
value_displaystringThe value formatted with the workspace locale and the deal currency.
currencystring | nullThree-letter currency code. Defaults to the board or workspace currency.
statusstringOpen while in a working stage; won or lost once it reaches a closing stage.
contact_idstring | nullContact the deal is with, or null.
contact_namestring | nullContact name.
contact_emailstring | nullContact email.
company_idstring | nullCompany the deal is with, or null.
company_namestring | nullCompany name.
owner_user_idinteger | nullWorkspace member who owns the deal, or null when unassigned.
owner_namestring | nullOwner name.
expected_close_onstring | nullExpected close date as a plain YYYY-MM-DD date, or null.
closed_atstring | nullWhen the deal was won or lost (set again if it moves between won and lost), or null while open.
lost_reasonstring | nullFree-text reason the deal was lost, kept when it did not match a reason on the workspace list. Null while the deal is open.
lost_reason_idstring | nullId of the chosen lost reason from the workspace list, or null.
lost_reason_labelstring | nullLabel of that lost reason.
sourcestring | nullWhere the deal came from.
notesstring | nullFree-text notes.
win_probabilitynumber | nullWin chance of the current stage, 0-100.
probability_overridenumber | nullWin chance set on this deal that replaces the stage figure, or null.
sort_orderintegerPosition within its stage.
sort_keynumber | nullOrdering key within its stage; lower comes first.
stage_entered_atstring | nullWhen the deal entered its current stage.
rotting_atstring | nullWhen the deal counts as stalled in its current stage, or null when the stage has no stall threshold.
next_activity_atstring | nullDue time of the earliest unfinished activity, or null.
last_activity_atstring | nullWhen activity was last logged, or null.
quote_idstring | nullQuote linked to the deal, or null.
created_atstringWhen the deal was created.
updated_atstringWhen the deal was last changed.

Request

curl --request PATCH \
  --url https://app.softsolz.uk/api/v1/services/pipelines/pipelines/{pipeline_id}/deals/{deal_id} \
  --header 'Authorization: Bearer sk_live_your_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "value_cents": 450000,
  "expected_close_on": "2026-12-01"
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 200

{
  "data": {
    "id": "345",
    "pipeline_id": "12",
    "stage_id": "71",
    "stage_name": "New",
    "title": "Acme Ltd - annual plan",
    "value_cents": 480000,
    "value_from_lines": false,
    "value_display": "£4,800.00",
    "currency": "GBP",
    "status": "open",
    "contact_id": null,
    "contact_name": null,
    "contact_email": null,
    "company_id": null,
    "company_name": null,
    "owner_user_id": null,
    "owner_name": null,
    "expected_close_on": "2026-12-15",
    "closed_at": null,
    "lost_reason": null,
    "lost_reason_id": null,
    "lost_reason_label": null,
    "source": "Website",
    "notes": "Asked for a demo next week.",
    "win_probability": 10,
    "probability_override": null,
    "sort_order": 0,
    "sort_key": 1000,
    "stage_entered_at": "2026-10-01T09:00:00.000Z",
    "rotting_at": null,
    "next_activity_at": "2026-10-09T10:00:00.000Z",
    "last_activity_at": null,
    "quote_id": null,
    "created_at": "2026-10-01T09:00:00.000Z",
    "updated_at": "2026-10-01T09:00:00.000Z"
  }
}