Update an opportunity

Operation ID: updateOpportunity

Group: CRM › Opportunities

Open in the interactive reference

PATCH /crm/opportunities/{id}

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Updates an opportunity. Every field is optional and an omitted field keeps its value; send null to clear endCustomerId, closeDate, amount or crmId. The rules apply to the opportunity as it will be afterward: the customer must belong to the entity, a partner customer needs one of its end customers, and the stage must be an active stage of the entity. Picking another customer drops the stored end customer unless you send a new one, and moving to another entity needs a stageId of that entity. Once a quote is linked, only opportunityName, stageId, closeDate and crmId can change (FIELD_LOCKED_BY_QUOTES); sending a locked field's current value is accepted. An opportunity in a Closed Won or Closed Lost stage cannot be changed (OPPORTUNITY_CLOSED); moving an open one into a closed stage is how it is closed. Opportunities of an entity kept in sync by a CRM integration cannot be changed here (OPPORTUNITIES_MANAGED_BY_INTEGRATION).

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.
id path string yes The opportunity to change. Example: "7d1c2b3a-9e8f-4a6b-b5c4-3d2e1f0a9b87".

Request body

Required, application/json: updateOpportunityInput.

Field Type Required Description
entityId string no The legal entity that owns the opportunity. It must be active, and the customer and stage must belong to it. Omit to leave unchanged. See id on GET base/entities.
customerId string no The customer or prospect the opportunity is for. Omit to leave unchanged. See id on GET accounting/customers/:id or GET crm/prospects/:id.
endCustomerId string | null no The end customer behind a partner customer. Omit to leave unchanged, or to drop it when customerId changes. Send null to clear. See id on GET accounting/customers/:id.
currency string no The currency the opportunity is denominated in, and the currency of amount. Format ISO 4217, for example 'USD'. Omit to leave unchanged.
priceBookId string no The price book quotes on this opportunity are priced from. Omit to leave unchanged. See id on GET accounting/price-books/:id.
stageId string no The stage the opportunity sits in: an active stage on GET crm/opportunity-stages/:id, where :id is the entity's id. Omit to leave unchanged. Example: "5b0e7c3a-2f6d-4a8b-9c1e-7d4f3a2b1c09".
opportunityName string no The display name of the opportunity. Must not be empty. Omit to leave unchanged.
closeDate date | null no The expected close date of the deal. Format YYYY-MM-DD. Omit to leave unchanged, send null to clear. Example: "2027-04-30".
amount decimal | null no The expected deal amount, as a decimal in currency. Omit to leave unchanged, send null to clear.
crmId string | null no The identifier of this opportunity in an external system, for example a Salesforce record id. Omit to leave unchanged, send null to clear. 
{
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "endCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "<currency>",
  "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "stageId": "5b0e7c3a-2f6d-4a8b-9c1e-7d4f3a2b1c09",
  "opportunityName": "<opportunityName>",
  "closeDate": "2027-04-30",
  "amount": "19.99",
  "crmId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response

200 Success

{
  "data": {},
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
NOT_FOUND 400
ENTITY_NOT_FOUND 400
OPPORTUNITIES_MANAGED_BY_INTEGRATION 400
INVALID_OPPORTUNITY_NAME 400
CUSTOMER_NOT_FOUND 400
CUSTOMER_NOT_IN_ENTITY 400
END_CUSTOMER_REQUIRED 400
INVALID_END_CUSTOMER 400
INVALID_CURRENCY 400
PRICE_BOOK_NOT_FOUND 400
STAGE_NOT_FOUND 400
OPPORTUNITY_CLOSED 400
FIELD_LOCKED_BY_QUOTES 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses