---
title: "Opportunities.update"
method: PATCH
path: "/entities/Opportunities/{id}"
tags: ["Lead & Opportunity"]
---

# Opportunities.update

`PATCH /entities/Opportunities/{id}`

Modifies Opportunity or Opportunities with given id(s)

## Path parameters

- `id` string, uuid, required

## Query parameters

- `validation-level` integer

## Request body

- UpdateOpportunityInput
  - `created` string, date-time — Creation time.
  - `active_quote_id` string, uuid — Id of the active quote.
  - `closing_date` string, date — Expected or actual closing date of the opportunity.
  - `currency_exchange_rates_list_id` string, uuid — Id of the currency exchange rate list applied to this opportunity.
  - `description` string — Free-form description of the opportunity.
  - `is_archived` boolean — True when the opportunity has been archived (lost). Archived opportunities remain readable but are hidden from active lists and cannot be edited until reactivated.
  - `is_value_auto_calculate` boolean — True when value is auto-calculated from the opportunity product line items. False when the user enters value directly.
  - `label_flag` string — User-set colored flag used to highlight the opportunity in lists and reports.
  - `last_ai_buying_center_applied` string, date-time — Time when an AI-suggested buying center was last applied to this opportunity.
  - `lead_source_id` string, uuid — Id of the lead source.
  - `name` string — Name of the entity and its default text representation.
  - `oppty_type_id` string, uuid — Id of the opportunity type.
  - `owner_id` string, uuid — Id of the opportunity owner.
  - `product_currency_id` string, uuid — Id of the product currency.
  - `product_price_list_id` string, uuid — Id of the product price list.
  - `product_sections` object — Product sections grouping the record's line items, as a JSON array of {"id": <UUID>, "name": <string>} objects. Validated on write. Full structure: https://graphql.api-doc.pipelinersales.com/latest/graphql/space/productsection.doc.html
  - `quick_account_email` string — Free-text company email captured at opportunity creation when no Account record has been linked yet.
  - `quick_account_name` string — Free-text company name captured at opportunity creation when no Account record has been linked yet.
  - `quick_account_phone` string — Free-text company phone captured at opportunity creation when no Account record has been linked yet.
  - `quick_contact_name` string — Free-text contact name captured at opportunity creation when no Contact record has been linked yet.
  - `quick_email` string — Free-text contact email captured at opportunity creation when no Contact record has been linked yet.
  - `quick_phone` string — Free-text contact phone captured at opportunity creation when no Contact record has been linked yet.
  - `ranking` integer — Qualitative ranking score (1-10) the user assigns to indicate the strength of the opportunity.
  - `reason_of_close_description` string — Free-form note explaining why the opportunity was archived (lost).
  - `reason_of_close_id` string, uuid — Id of the reason-of-close value.
  - `share_mode` 0 | 1 | 2 | 3 — Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit
  - `step_id` string, uuid — Id of the pipeline step.
  - `unit_id` string, uuid — Id of the sales unit.
  - `was_qualified` boolean — True when the opportunity has gone through the qualification step at least once.
  - `revision` integer — Revision when entity was lastly changed.
  - `value` object — Monetary value of the opportunity in the team space base currency, with the foreign value and currency code preserved alongside.
    - `base_value` number, double, required — Currency.
    - `currency_id` string, uuid, required — Relation to single entity instance.
    - `value_foreign` number, double, required — Decimal number.
  - `oppty_recurrence` object — Recurrence schedule generating periodic copies of this opportunity, or empty when no recurrence is set up. Relation to OpptyRecurrence, see: 'updateOpptyRecurrenceInput' object for properties.
    - `id` string, uri
  - `revenue_schedule` object — Revenue schedule splitting the opportunity value across periods, or empty when revenue scheduling is not enabled for this opportunity. Relation to OpptyRevenueSchedule, see: 'updateOpptyRevenueScheduleInput' object for properties.
    - `id` string, uri
  - `product_relations` object[] — Product line items on this opportunity. Each entry holds the product, quantity, price and discount that contribute to the opportunity value when is_value_auto_calculate is true.
    - `id` string, uri
  - `contact_relations` object[] — Contacts linked to this opportunity, including their roles and org-chart positions.
    - `id` string, uri
  - `account_relations` object[] — Accounts linked to this opportunity, including the primary-account flag.
    - `id` string, uri
  - `documents` object[] — Documents linked to this opportunity.
    - `id` string, uri
  - `quote_relations` object[] — Quotes prepared for this opportunity.
    - `id` string, uri
  - `won_date` string, date-time — Timestamp of when the opportunity was won. Setting it adjusts the underlying win event; empty for opportunities that have not been won.
  - `lost_date` string, date-time — Timestamp of when the opportunity was archived (lost). Setting it adjusts the underlying loss event; empty for opportunities that have not been archived.
  - `sharing_units` object[] — Sales units that have been granted shared access to this opportunity. Editable only when share_mode allows unit sharing.
    - `id` string, uri
  - `sharing_clients` object[] — Users that have been granted shared access to this opportunity. Editable only when share_mode allows user sharing.
    - `id` string, uri
  - `tags` object[] — Tag labels applied to this opportunity.
    - `id` string, uri
  - `static_profiles` object[] — Saved view profiles this opportunity currently matches.
    - `id` string, uri

## Response `200`

Modification confirmation. Returns resulting Opportunity

- object
  - `success` boolean — True when response succeeded, false on error.
  - `data` Opportunity
    - `is_delete_protected` boolean, required — Tells if the entity instance is protected against delete (Entities that need to be present in the system at any time). Delete action still may fail if entity is deletable, due some other additional validations.
    - `id` string, uuid, required — Unique identifier of entity.
    - `is_deleted` boolean — Specifies if the entity is considered deleted.
    - `modified` string, date-time — Last modification time.
    - `created` string, date-time — Creation time.
    - `active_quote` string, uri — Quote currently used to drive the opportunity (e.g. for synchronisation of monetary fields). Empty when no quote is active. Relation to Quote. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Quote' object for properties.
    - `currency_exchange_rates_list` string, uri — Currency exchange rate list used to convert monetary fields linked to this opportunity. Empty to inherit the team space default. Relation to CurrencyExchangeRatesList. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'CurrencyExchangeRatesList' object for properties.
    - `lead_source` string, uri — How the opportunity originated (e.g. Website, Referral, Trade Show). Configurable per team space. Relation to Data. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Data' object for properties.
    - `oppty_type` string, uri, required — Opportunity type that classifies this opportunity. Each type maps to one pipeline and drives which form, fields and stages apply. Relation to OpportunityType. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'OpportunityType' object for properties.
    - `owner` string, uri, required — Sales user who owns this opportunity. Relation to Client. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Client' object for properties.
    - `product_currency` string, uri, required — Currency used for product line-item prices on this opportunity. Relation to Currency. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Currency' object for properties.
    - `product_price_list` string, uri — Product price list used to populate prices for product line items added to this opportunity. Empty to use catalog defaults. Relation to ProductPriceList. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'ProductPriceList' object for properties.
    - `reason_of_close` string, uri — Configurable reason recorded when the opportunity is archived (lost). Required when the lost form mandates it. Relation to Data. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Data' object for properties.
    - `step` string, uri, required — Pipeline step the opportunity is currently sitting in. Reaching the last step in the pipeline marks the opportunity as won; archiving sets it to lost. Relation to Step. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Step' object for properties.
    - `unit` string, uri, required — Sales unit this opportunity is assigned to. Determines which team members can see the record under unit-based sharing. Relation to SalesUnit. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'SalesUnit' object for properties.
    - `active_quote_id` string, uuid — Id of the active quote.
    - `closing_date` string, date, required — Expected or actual closing date of the opportunity.
    - `currency_exchange_rates_list_id` string, uuid — Id of the currency exchange rate list applied to this opportunity.
    - `description` string — Free-form description of the opportunity.
    - `is_archived` boolean — True when the opportunity has been archived (lost). Archived opportunities remain readable but are hidden from active lists and cannot be edited until reactivated.
    - `is_value_auto_calculate` boolean — True when value is auto-calculated from the opportunity product line items. False when the user enters value directly.
    - `label_flag` string — User-set colored flag used to highlight the opportunity in lists and reports.
    - `last_ai_buying_center_applied` string, date-time — Time when an AI-suggested buying center was last applied to this opportunity.
    - `lead_source_id` string, uuid — Id of the lead source.
    - `name` string, required — Name of the entity and its default text representation.
    - `oppty_type_id` string, uuid — Id of the opportunity type.
    - `owner_id` string, uuid, required — Id of the opportunity owner.
    - `product_currency_id` string, uuid — Id of the product currency.
    - `product_price_list_id` string, uuid — Id of the product price list.
    - `product_sections` object — Product sections grouping the record's line items, as a JSON array of {"id": <UUID>, "name": <string>} objects. Validated on write. Full structure: https://graphql.api-doc.pipelinersales.com/latest/graphql/space/productsection.doc.html
    - `quick_account_email` string — Free-text company email captured at opportunity creation when no Account record has been linked yet.
    - `quick_account_name` string — Free-text company name captured at opportunity creation when no Account record has been linked yet.
    - `quick_account_phone` string — Free-text company phone captured at opportunity creation when no Account record has been linked yet.
    - `quick_contact_name` string — Free-text contact name captured at opportunity creation when no Contact record has been linked yet.
    - `quick_email` string — Free-text contact email captured at opportunity creation when no Contact record has been linked yet.
    - `quick_phone` string — Free-text contact phone captured at opportunity creation when no Contact record has been linked yet.
    - `ranking` integer — Qualitative ranking score (1-10) the user assigns to indicate the strength of the opportunity.
    - `reason_of_close_description` string — Free-form note explaining why the opportunity was archived (lost).
    - `reason_of_close_id` string, uuid — Id of the reason-of-close value.
    - `share_mode` 0 | 1 | 2 | 3 — Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit
    - `step_id` string, uuid, required — Id of the pipeline step.
    - `table_name` string, required — Discriminator identifying the concrete record type — always "opportunity" for Opportunity records. Read-only; useful when consuming polymorphic LeadOppty results.
    - `unit_id` string, uuid — Id of the sales unit.
    - `was_qualified` boolean — True when the opportunity has gone through the qualification step at least once.
    - `revision` integer — Revision when entity was lastly changed.
    - `value` object, required — Monetary value of the opportunity in the team space base currency, with the foreign value and currency code preserved alongside.
      - `base_value` number, double, required — Currency.
      - `currency_id` string, uuid, required — Relation to single entity instance.
      - `value_foreign` number, double, required — Decimal number.
    - `oppty_recurrence` string, uri — Recurrence schedule generating periodic copies of this opportunity, or empty when no recurrence is set up. Relation to OpptyRecurrence. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'OpptyRecurrence' object for properties.
    - `revenue_schedule` string, uri — Revenue schedule splitting the opportunity value across periods, or empty when revenue scheduling is not enabled for this opportunity. Relation to OpptyRevenueSchedule. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'OpptyRevenueSchedule' object for properties.
    - `product_relations` string[] — Product line items on this opportunity. Each entry holds the product, quantity, price and discount that contribute to the opportunity value when is_value_auto_calculate is true.
    - `primary_contact` string, uri — Primary contact of this opportunity. Set automatically from the contact relation marked as primary. Relation to Contact. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Contact' object for properties.
    - `primary_account` string, uri — Primary account of this opportunity. Set automatically from the account relation marked as primary. Relation to Account. By default it is returned as URI to related resource. Using parameter 'expand', it will return full entity. See: 'Account' object for properties.
    - `contact_relations` string[] — Contacts linked to this opportunity, including their roles and org-chart positions.
    - `account_relations` string[] — Accounts linked to this opportunity, including the primary-account flag.
    - `documents` string[] — Documents linked to this opportunity.
    - `quote_relations` string[] — Quotes prepared for this opportunity.
    - `status` 1 | 2 | 3, required — Current status of the opportunity (Open, Won, Lost). Read-only; derived from the current pipeline step and the archived flag. Integer enum value: 1 - Open, 2 - Lost, 3 - Won
    - `qualify_date` string, date-time — Timestamp of when the opportunity was qualified, taken from the matching KPI event. Empty for opportunities that have not been qualified. Read-only.
    - `won_date` string, date-time — Timestamp of when the opportunity was won. Setting it adjusts the underlying win event; empty for opportunities that have not been won.
    - `lost_date` string, date-time — Timestamp of when the opportunity was archived (lost). Setting it adjusts the underlying loss event; empty for opportunities that have not been archived.
    - `days_in_step` integer, required — Number of days the opportunity has been sitting in its current pipeline step. Read-only; computed by Coevera from the most recent move event and per-step timeframe history.
    - `is_favorite` boolean, required — True when the current authenticated user has marked this opportunity as favorite. Per-user.
    - `sharing_units` string[] — Sales units that have been granted shared access to this opportunity. Editable only when share_mode allows unit sharing.
    - `sharing_clients` string[] — Users that have been granted shared access to this opportunity. Editable only when share_mode allows user sharing.
    - `tags` string[] — Tag labels applied to this opportunity.
    - `static_profiles` string[] — Saved view profiles this opportunity currently matches.
    - `formatted_name` string, required — Display version of the opportunity name, used in lists and references.
    - `modified_by_user` string, date-time — Timestamp of the most recent modification made by an end user (excluding system changes). Read-only; computed by Coevera.

## Other responses

- `404` — Sent when invalid ID is given
- `500` — unexpected error

---

[API](https://skmtc.net/aws/apis/pipeliner-cloud-api.md) · [All operations](https://skmtc.net/aws/apis/pipeliner-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/pipeliner-cloud-api/versions/e8c12ae60aca/schema)