> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an opportunity

> Changes only the keys sent: standard fields at the top level (name, description, stage, type, amount, close_date, owner), custom fields under `fields`. `null` clears a field that may be empty: not name, stage or type, nor a mandatory custom field. A change to a standard field is the app's own edit: until your CRM has received it, the CRM sync does not overwrite the opportunity. Where your workspace syncs opportunities with Salesforce or HubSpot (describe's `syncs_to_crm` says which fields) and the account is linked to an account in that CRM (a company, in HubSpot), the next push sends name, amount, stage, type and close date, plus owner to Salesforce (never description), and creates the opportunity there if it has no `crm_opportunity_id` yet. An update that sends only `fields` leaves the standard fields to the CRM sync. A new `stage` sets `is_closed` and `is_won` from that stage. Every key is checked before anything is written, and any problem refuses the whole request with a 422 listing each one in `details`: a stage outside your stage list (where one is set up), an owner who is not a user, a field describe marks `writable: false`. Once the keys pass, your admin's validation rules run over the merged record; a change that breaks one is a 422 whose `details` name each rule, and nothing is written. The API does not move an opportunity to another account (`account` is not writable); your CRM sync may. Returns the updated opportunity.



## OpenAPI

````yaml /api/statisfy-api.openapi.json patch /v1/objects/opportunity/records/{opportunity_id}
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/objects/opportunity/records/{opportunity_id}:
    patch:
      tags:
        - opportunities
      summary: Update an opportunity
      description: >-
        Changes only the keys sent: standard fields at the top level (name,
        description, stage, type, amount, close_date, owner), custom fields
        under `fields`. `null` clears a field that may be empty: not name, stage
        or type, nor a mandatory custom field. A change to a standard field is
        the app's own edit: until your CRM has received it, the CRM sync does
        not overwrite the opportunity. Where your workspace syncs opportunities
        with Salesforce or HubSpot (describe's `syncs_to_crm` says which fields)
        and the account is linked to an account in that CRM (a company, in
        HubSpot), the next push sends name, amount, stage, type and close date,
        plus owner to Salesforce (never description), and creates the
        opportunity there if it has no `crm_opportunity_id` yet. An update that
        sends only `fields` leaves the standard fields to the CRM sync. A new
        `stage` sets `is_closed` and `is_won` from that stage. Every key is
        checked before anything is written, and any problem refuses the whole
        request with a 422 listing each one in `details`: a stage outside your
        stage list (where one is set up), an owner who is not a user, a field
        describe marks `writable: false`. Once the keys pass, your admin's
        validation rules run over the merged record; a change that breaks one is
        a 422 whose `details` name each rule, and nothing is written. The API
        does not move an opportunity to another account (`account` is not
        writable); your CRM sync may. Returns the updated opportunity.
      operationId: opportunities_update
      parameters:
        - in: path
          name: opportunity_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              properties:
                amount:
                  default: null
                  description: The deal's value
                  title: Amount
                  type: number
                close_date:
                  default: null
                  description: YYYY-MM-DD
                  format: date
                  title: Close Date
                  type: string
                description:
                  default: null
                  description: Free text
                  title: Description
                  type: string
                fields:
                  anyOf:
                    - additionalProperties: true
                      type: object
                    - type: 'null'
                  default: null
                  description: Custom field keys to values
                  title: Fields
                name:
                  default: null
                  description: The opportunity's name (required on a create)
                  title: Name
                  type: string
                owner:
                  default: null
                  description: The owner's user id
                  title: Owner
                  type: string
                stage:
                  default: null
                  description: >-
                    One of your stages (key or label) where your stage list is
                    set up
                  title: Stage
                  type: string
                type:
                  default: null
                  description: New Business, Renewal, Expansion, ...
                  title: Type
                  type: string
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    Opportunity:
      properties:
        account:
          anyOf:
            - type: string
            - type: 'null'
          description: The id of the account the opportunity is on
          title: Account
        account_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Name
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
        close_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Close Date
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        crm_opportunity_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Crm Opportunity Id
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        fields:
          additionalProperties: true
          title: Fields
          type: object
        id:
          title: Id
          type: string
        is_closed:
          default: false
          title: Is Closed
          type: boolean
        is_won:
          default: false
          title: Is Won
          type: boolean
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        owner:
          anyOf:
            - type: string
            - type: 'null'
          description: The owner's user id
          title: Owner
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Stage
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
      required:
        - id
      title: Opportunity
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.