Suger

Update a co-sell referral (incl. status / stage transitions)

PATCH https://api.suger.cloud/org/{orgId}/cosell/referral/{referralId}

Update fields of an existing co-sell referral. Used primarily for business field edits (amount, close date, contacts, etc.). Supports AWS / AZURE / GCP / SUGER. Send only the fields being changed. Do not read a referral and send the whole object back: on a partner's copy of a Suger referral whose deal value is hidden, the read returns `dealValueAmount`, `dealValueCurrency` and `sharePercentage` blanked out, and echoing those blanks back writes them or fails validation. Legal Suger unified status values (DB enum, UPPER_SNAKE_CASE): DRAFT, PENDING_CREATE, CREATE_FAILED, UPDATE_FAILED, IN_REVIEW, PENDING_ACCEPTANCE, ACTION_REQUIRED, ACTIVE, EXPIRED, CLOSED_WON, CLOSED_LOST, CLOSED_ERROR, REJECTED. IMPORTANT: For AWS the unified `status` is recomputed server-side from `info.aceOpportunityV2.lifeCycle`; passing a top-level `status` is not the way to drive state transitions. Instead, edit the partner-specific lifecycle fields and let the server derive `status`. For AWS inbound referrals, sending a body with `info.aceEngagementInvitation` (and no `info.aceOpportunityV2`) triggers the accept/reject engagement-invitation flow. For `partner=SUGER` (a referral shared with a partner company), this is also how the recipient responds to one they received, while it is still PENDING_ACCEPTANCE. To accept, send EITHER `status` ACTIVE OR `stage` Active — one is enough, and sending both is accepted too. To decline, set `status` to REJECTED and supply `declineReason`; the request is refused without a reason. Only the company that received the referral can respond, and only its own copy is in that state; the sender withdraws instead. Both responses reach the other side automatically. While a referral is still PENDING_ACCEPTANCE the recipient can ONLY accept or decline it. Sending `nextSteps`, `closedLostReason`, `customerInfo`, `dealDetails` or `revenueShareTerms` in the same request is rejected with a message naming the field — accept first, then send the edit as a second call. NOTE: for AWS / AZURE / GCP, changing fields here only updates Suger — call SyncSingleReferral with `direction=OUTBOUND` afterwards to push the change to the cloud partner. A SUGER referral needs no such call: the partner's copy is kept in step by Suger itself. SyncSingleReferral on a SUGER referral synchronizes the linked CRM record, which is a different thing. Use this when: user wants to edit a referral's fields, accept or decline a referral a partner shared with them, or progress an AWS inbound referral via invitation accept/reject.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID
referralId path string yes Cosell Referral ID
isLinkageUpdate query boolean no When true, persist ONLY the CRM-linkage fields (salesforceOpportunityId / salesforceAccountId / hubspotDealId / dynamics365OpportunityId) and skip the partner update validator and outbound sync. The body's partner-opportunity content is ignored. Use this for an account/opportunity match that must link even when the referral's partner-opp would otherwise fail validation (e.g. an AWS referral at Committed stage still carrying solution \
syncToSlack query boolean no When true, mirror the new all-visibility root conversation(s) in this request to the partner's Slack channel (the 'Slack thread' composer mode). Plain Comments and internal notes leave it false; replies mirror based on their root regardless of this flag. Request-only — never persisted.

Request Body

Required. Content-Type: application/json · Schema: orm.CosellReferral

orm.CosellReferral fields:

FieldTypeRequiredDescription
approvalInfo ApprovalInfo no
contactIDs array<string> no ContactIds holds the value of the "contact_ids" field.
creationRetryCount integer no CreationRetryCount holds the value of the "creation_retry_count" field.
creationTime string no CreationTime holds the value of the "creation_time" field.
direction cosellreferral.Direction no
dynamics365OpportunityId string no Dynamics365OpportunityID holds the value of the "dynamics365_opportunity_id" field.
errorMessages array<string> no ErrorMessages holds the value of the "error_messages" field.
externalCreationTime string no ExternalCreationTime holds the value of the "external_creation_time" field.
externalId string no ExternalID holds the value of the "external_id" field.
externalLastUpdateTime string no ExternalLastUpdateTime holds the value of the "external_last_update_time" field.
hubspotDealId string no HubspotDealID holds the value of the "hubspot_deal_id" field.
id string no ID of the ent.
info ReferralInfo no
lastUpdateTime string no LastUpdateTime holds the value of the "last_update_time" field.
metaInfo ReferralMetaInfo no
name string no Name holds the value of the "name" field.
organizationId string no OrganizationID holds the value of the "organization_id" field.
partner cosellreferral.Partner no
partnerId string no PartnerID holds the value of the "partner_id" field.
partnerStatus string no PartnerStatus holds the value of the "partner_status" field.
salesforceAccountId string no SalesforceAccountID holds the value of the "salesforce_account_id" field.
salesforceOpportunityId string no SalesforceOpportunityID holds the value of the "salesforce_opportunity_id" field.
salesforceReferralId string no SalesforceReferralID holds the value of the "salesforce_referral_id" field.
stage string no Stage holds the value of the "stage" field.
status string no Status holds the value of the "status" field.

ApprovalInfo fields:

FieldTypeRequiredDescription
approvalStatus ApprovalStatus no
decisionDate string no DecisionDate is when the final approval/decline happened (nil when pending) Latest DecisionDate
message string no Message is the reason or explanation provided when the approval status is set to Declined or Action Required. It always stores the latest message for the current status transition. Historical messages are stored in notification events.
requestDate string no Latest RequestDate

ReferralInfo fields:

FieldTypeRequiredDescription
aceEngagementInvitation types.EngagementInvitation no
aceOpportunity AceOpportunity no
aceOpportunityV2 types.AceOpportunityV2 no
aceOutboundEngagementInvitations array<types.EngagementInvitation> no AceOutboundEngagementInvitations stores all outbound engagement invitations sent to partners.
createMicrosoftReferralRequest CreateReferralRequest no
gcpOpportunity GCPOpportunity no
gcpOpportunityV2 types.Opportunity no
microsoftReferralSet MicrosoftReferralSet no
sugerOpportunity SugerOpportunity no

ReferralMetaInfo fields:

FieldTypeRequiredDescription
archivedAt string no ArchivedAt is the time when the referral was deleted. It is set to indicate that the referral has been archived; otherwise, the referral is considered active.
autoConnectedManagedAccount boolean no AutoConnectedManagedAccount is true when Suger's Auto Share auto-picked the Microsoft Managed Account for this referral's customer (vs CRM-mapped or user-selected). Azure-only. Set at submission time and never cleared.
awsInvitePartnerRequests array<SendEngagementInvitationRequest> no AwsInvitePartnerRequests stores the list of partners to invite when creating this referral. Each entry is passed to SendEngagementInvitation() after engagement creation completes. This field is never cleared — it serves as a permanent record of invitation intent and allows retry via the standalone SendEngagementInvitation endpoint. Max 9 partners per opportunity (AWS API limit).
azureDealRegIsEligible boolean no AzureDealRegIsEligible indicates whether the referral is eligible for Azure deal registration. This is pre-computed by a daily cron workflow and cached here.
createdByEmail string no The email address of the user who created the referral. This field is immutable after creation. Especially useful for referrals created from Salesforce/HubSpot integrations where the creator may not have a Suger account yet.
createdBySource CreatedBySource no
creationFailureMessage string no
creationStatus string no
crmOpportunityId string no
crmPartner string no
hubspotDealId string no
isTesting boolean no IsTesting is a flag to indicate if the referral is for testing purpose. E.g., customer doing a POC without a real ACE connection.
lastSyncMessage string no
lastSyncStatus string no
lastSyncTime string no
predictedQualityScore structs.PredictedQualityScoreSnapshot no
salesforceReferralId string no
syncDisabled boolean no
updateFailureMessage string no
updateStatus string no

types.EngagementInvitation fields:

FieldTypeRequiredDescription
Arn string no
Catalog string no
EngagementDescription string no
EngagementId string no
EngagementTitle string no
ExistingMembers array<github_com_sugerio_marketplace-service_pkg_integration_ace_types.EngagementMember> no
ExpirationDate string no
Id string no
InvitationDate string no
InvitationMessage string no
Payload types.EngagementInvitationPayload no
PayloadType string no
Receiver github_com_sugerio_marketplace-service_pkg_integration_ace_types.Receiver no
RejectionReason string no
SenderAwsAccountId string no
SenderCompanyName string no
Status string no

AceOpportunity fields:

FieldTypeRequiredDescription
IsOppFromMarketingActivity string no Note that the JSON field's first letter must be uppercase.
aWSAccountOwnerEmail string no
aWSAccountOwnerName string no
aWSCloseDate string no
aWSClosedLostReason string no
aWSISVSuccessManagerEmail string no
aWSISVSuccessManagerName string no
aWSPartnerSuccessManagerEmail string no
aWSPartnerSuccessManagerName string no
aWSSalesRepEmail string no
aWSSalesRepName string no
aWSStage string no
acceptBy string no
additionalComments string no
apnCrmLeadUniqueIdentifier string no
apnCrmUniqueIdentifier string no
apnReviewerComments string no
awsAccountId string no
awsProducts array<string> no
awsSFCampaignName string no
backwardsCompatibilityChanges string no
campaignName string no
city string no
closedLostReason string no
competitiveTracking string no
competitiveTrackingOther string no
contractEndDate string no
contractStartDate string no
cosellConvertReason string no
country string no
createdBy string no
createdDate string no
customerCompanyName string no
customerDuns string no
customerEmail string no
customerFirstName string no
customerLastName string no
customerPhone string no
customerSoftwareValue number no
customerSoftwareValueCurrency string no
customerTitle string no
customerWebsite string no
deliveryModel string no
doesOppBelongToNatSec string no
engagementInvitationArn string no For Partner Central API inbound opportunity
engagementScore string no
expectedMonthlyAwsRevenue integer no
industry string no
industryOther string no
isMarketingDevelopmentFunded string no
lastModifiedBy string no
lastModifiedDate string no
marketingActivityChannel string no
marketingActivityUsecase string no
nextStep string no
nextStepHistory string no
offers array<string> no
opportunityOwnerEmail string no
opportunityOwnerName string no
opportunityOwnership string no
opportunityType string no
otherSolutionOffered string no
parentOppId string no When Opportunity Type is set to "Flat Renewal". Mandatory when partner needs to send updates to existing opportunities.
partnerAcceptanceDate string no
partnerAcceptanceStatus string no
partnerCrmUniqueIdentifier string no
partnerDeveloperManager string no
partnerDeveloperManagerEmail string no
partnerPrimaryNeedFromAws string no
partnerProjectTitle string no
postalCode string no
primaryContactEmail string no
primaryContactFirstName string no
primaryContactLastName string no
primaryContactPhone string no
primaryContactTitle string no
procurementType string no
projectDescription string no
recommendedNextBestActions string no
rejectionReason string no
salesActivities string no
solutionOffered array<string> no
stage string no
state string no
status string no
streetAddress string no
sugerRequestId string no Suger-internal field to store the request id.
targetCloseDate string no
useCase string no
wWPSPDM string no
wWPSPDMEmail string no

types.AceOpportunityV2 fields:

FieldTypeRequiredDescription
AWSLifeCycle github_com_sugerio_marketplace-service_pkg_integration_ace_types.LifeCycle no
AWSOpportunityTeam array<github_com_sugerio_marketplace-service_pkg_integration_ace_types.Contact> no AWSOpportunityTeam details the AWS opportunity team, including members involved. This information helps partners know who from AWS is engaged and what their role is.
Arn string no Arn, The Amazon Resource Name (ARN) that uniquely identifies the opportunity. Type: String Pattern: ^arn:.*$
Catalog string no Specifies the catalog associated with the request. This field takes a string value from a predefined list: AWS or Sandbox. The catalog determines which environment the opportunity is created in. Use AWS to create opportunities in the AWS catalog, and Sandbox to test in a secure and isolated environment. Type: String Pattern: ^[a-zA-Z]+$ Required: Yes
CosellMotion string no CosellMotion classifies how AWS is engaging with this opportunity. Operational classification produced by AWS's routing model — not an analytical insight. Populated asynchronously after submission; empty string until classified. Values are extensible — new motions may be added without notice. Type: String Known Values: AWS Field-engaged | Agent-engaged | Partner-led
CreatedDate string no DateTime when the Opportunity was last created.
Customer github_com_sugerio_marketplace-service_pkg_integration_ace_types.Customer no
Id string no ID Read-only, system generated Opportunity unique identifier. Type: String Pattern: ^O[0-9]{1,19}$
Insights types.Insights no
InvolvementType string no InvolvementType specifies the type of involvement AWS has in the opportunity, such as direct cosell or advisory support. This field helps partners understand the role AWS plays in advancing the opportunity. Type: String Valid Values: For Visibility Only | Co-Sell
InvolvementTypeChangeReason string no InvolvementTypeChangeReason provides a reason for any changes in the involvement type of AWS in the opportunity. This field is used to track why the level of AWS engagement has changed from For Visibility Only to Co-sell offering transparency into the partnership dynamics. Type: String Valid Values: Expansion Opportunity | Change in Deal Information | Customer Requested | Technical Complexity | Risk Mitigation
LastModifiedDate string no DateTime when the opportunity was last modified.
LifeCycle github_com_sugerio_marketplace-service_pkg_integration_ace_types.LifeCycle no
Marketing github_com_sugerio_marketplace-service_pkg_integration_ace_types.Marketing no
NationalSecurity string no Indicates whether the Opportunity pertains to a national security project. This field must be set to true only when the customer's industry is Government. Additional privacy and security measures apply during the review and management process for opportunities marked as NationalSecurity. Type: String Valid Values: Yes | No Required: No
OpportunityTeam array<github_com_sugerio_marketplace-service_pkg_integration_ace_types.Contact> no Represents the internal team handling the opportunity. Specify the members involved in collaborating on this opportunity within the partner's organization. Type: Array of Contact objects Array Members: Minimum number of 0 items. Maximum number of 1 item. Required: No
OpportunityType string no Specifies the opportunity type as a renewal, new, or expansion. Opportunity types: New opportunity: Represents a new business opportunity with a potential customer that's not previously engaged with your solutions or services. Renewal opportunity: Represents an opportunity to renew an existing contract or subscription with a current customer, ensuring continuity of service. Expansion opportunity: Represents an opportunity to expand the scope of an existing contract or subscription, either by adding new services or increasing the volume of existing services for a current customer. Type: String Valid Values: Net New Business | Flat Renewal | Expansion Required: No
Origin string no Specifies the origin of the opportunity, indicating if it was sourced from AWS or the partner. For all opportunities created with Catalog: AWS, this field must only be Partner Referral. However, when using Catalog: Sandbox, you can set this field to AWS Referral to simulate AWS referral creation. This allows AWS-originated flows testing in the sandbox catalog. Type: String Valid Values: AWS Referral | Partner Referral Required: No
PartnerOpportunityIdentifier string no Specifies the opportunity's unique identifier in the partner's CRM system. This value is essential to track and reconcile because it's included in the outbound payload sent back to the partner. This field allows partners to link an opportunity to their CRM, to ensure seamless integration and accurate synchronization between the Partner Central API and the partner's internal systems. Type: String Length Constraints: Minimum length of 0. Maximum length of 64. Required: No
PrimaryNeedsFromAws array<string> no Identifies the type of support the partner needs from AWS. Valid values: Co-Sell - Architectural Validation: Confirmation from AWS that the partner's proposed solution architecture is aligned with AWS best practices and poses minimal architectural risks. Co-Sell - Business Presentation: Request AWS seller's participation in a joint customer presentation. Co-Sell - Competitive Information: Access to AWS competitive resources and support for the partner's proposed solution. Co-Sell - Pricing Assistance: Connect with an AWS seller for support situations where a partner may be receiving an upfront discount on a service (for example: EDP deals). Co-Sell - Technical Consultation: Connect with an AWS Solutions Architect to address the partner's questions about the proposed solution. Co-Sell - Total Cost of Ownership Evaluation: Assistance with quoting different cost savings of proposed solutions on AWS versus on-premises or a traditional hosting environment. Co-Sell - Deal Support: Request AWS seller's support to progress the opportunity (for example: joint customer call, strategic positioning). Co-Sell - Support for Public Tender / RFx: Opportunity related to the public sector where the partner needs AWS RFx support. Do Not Need Support from AWS Sales Rep: Indicates that a partner doesn't need support from an AWS sales representative, and the partner solely manages the opportunity. It's possible to request co-selling support on these opportunities at any stage during their lifecycle. Also known as, for-visibility-only (FVO) opportunity. Type: Array of strings Valid Values: Co-Sell - Architectural Validation | Co-Sell - Business Presentation | Co-Sell - Competitive Information | Co-Sell - Pricing Assistance | Co-Sell - Technical Consultation | Co-Sell - Total Cost of Ownership Evaluation | Co-Sell - Deal Support | Co-Sell - Support for Public Tender / RFx Required: No
Project github_com_sugerio_marketplace-service_pkg_integration_ace_types.Project no
RelatedEntityIdentifiers github_com_sugerio_marketplace-service_pkg_integration_ace_types.RelatedEntityIdentifiers no
SoftwareRevenue github_com_sugerio_marketplace-service_pkg_integration_ace_types.SoftwareRevenue no
Visibility string no Visibility defines the visibility level for the AWS Opportunity. Use Full visibility for most cases, while Limited visibility is reserved for special programs or sensitive opportunities. Type: String Valid Values: Full | Limited

CreateReferralRequest fields:

FieldTypeRequiredDescription
attributes object no
callToAction string no
campaignId string no
consent MicrosoftPartnerReferralConsent no
contract MicrosoftPartnerReferralContract no
customerProfile MicrosoftPartnerReferralProfile no
dealType DealType no
details MicrosoftPartnerReferralDetail no
engagementId string no
expirationDateTime string no
externalReferenceId string no
invitations array<InvitationToPartner> no Additional properties from Suger, used to generate connected referrals Details and Team are mandatory for non-msft invitations
inviteContext MicrosoftPartnerReferralInviteContext no
mpnId string no
name string no
organizationId string no
organizationName string no
qualification MicrosoftPartnerReferralQualification no
status MicrosoftPartnerReferralStatus no
statusReason string no
substatus MicrosoftPartnerReferralSubStatus no
target array<MicrosoftPartnerReferralTarget> no
team array<MicrosoftPartnerReferralPerson> no
type MicrosoftPartnerReferralType no

GCPOpportunity fields:

FieldTypeRequiredDescription
approvedDate string no
authority string no
budget string no
campaignCode string no
closeDate string no
closeDatePushCount integer no
confidential boolean no
contractExpiryDate string no
contractLengthMonths integer no
contractVehicle string no
customerAddressAdministrativeArea string no
customerAddressLanguageCode string no
customerAddressLines array<string> no
customerAddressLocality string no
customerAddressOrganization string no
customerAddressPostalCode string no
customerAddressRecipients array<string> no
customerAddressRegionCode string no
customerAddressRevision integer no
customerAddressSortingCode string no
customerAddressSublocality string no
customerContactEmail string no
customerContactFamilyName string no
customerContactGivenName string no
customerContactPhone object no
customerContactRequested boolean no
customerContacts array<object> no
customerDisplayName string no
customerDomain string no
customerEmployeeCount integer no
customerIndustry string no
customerOrganizationName string no
customerRegion string no
dealNumber string no
dealSize object no
decisionPhase string no
deliveryModel string no
distributor string no
estimatedCloseDate string no
extensionsCount integer no
gcpCreatedDate string no
gcpCreatorEmail string no
gcpName string no
gcpOwner string no
gcpOwnerEmail string no
gcpProjectNumbers array<string> no
gcpSource string no
gcpStage string no
gcpState string no
gcpStateDescription string no
gcpUpdatedDate string no
gcpWatermark number no
id string no
incentiveEligibility boolean no
incentiveType string no
indirectPartnerEntity string no
isvSolutionConnectDeal boolean no
legalLanguageAccepted boolean no
lostMainReason string no
lostReason string no
lostRejectedReasonDetails string no
msspDeal boolean no
need string no
operationType string no
opportunityAmount object no
opportunityDescription string no
opportunityDisplayName string no
opportunityLines array<object> no
opportunityTeamMembers array<object> no
opportunityType string no
partnerEntity string no
partnerReadyToClose string no
prmSiteDetails string no
productCategory array<string> no
productFamily array<string> no
publicSector boolean no
rebateExpirationDate string no
rebateExtensions array<object> no
subbillingAccountId string no
submittedDate string no
supportLevel string no
timeline string no
winLossAdditionalContext string no
winLossProducts array<string> no
winMainReason string no
wonReason string no

types.Opportunity fields:

FieldTypeRequiredDescription
createTime string no Output only. CreateTime is the time when the Opportunity was created.
creationDate types.GcpCosellDate no
creatorEmail string no Output only. CreatorEmail is the email of the user who created the Opportunity.
customerContacts array<types.CustomerContact> no List of Customer contacts for the Opportunity, present after approval. Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
customerDisplayName string no Output only. CustomerDisplayName is the display name of the customer associated with the Opportunity.
customerInfo types.CustomerInfo no
isvSolutionConnectInfo types.IsvSolutionConnectInfo no
name string no Name is the identifier for the Opportunity in the format: opportunities/{opportunity_id}.
opportunityInfo types.OpportunityInfo no
opportunityLines array<types.OpportunityLine> no Information about the products added to the Opportunity Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
opportunityTeamMembers array<types.OpportunityTeamMember> no Information on the Partner users with access to the Opportunity Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
opportunityType string no Optional. Indicates if the opportunity is a Regular/Independent Software Vendor/2-tier deal. If not specified, it will be treated as a Regular. Can't be edited after the Opportunity is Accepted.
owner string no Output only. Owner is the name of the Google FSR (Field Sales Representative) who owns the Opportunity.
ownerEmail string no Output only. OwnerEmail is the email of the Google FSR who owns the Opportunity.
partnerInfo types.PartnerInfo no
qualificationInfo types.QualificationInfo no
rebateExtensions array<types.RebateExtension> no Information about rebate extensions requested on the Opportunity. Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
salesCycle types.SalesCycle no
source string no Output only. Source indicates if the Opportunity was created by Google or a Partner.
stage types.GCPOppoStage no
state types.GCPOppoState no
stateDescription string no Output only. StateDescription contains the reason if the Opportunity was not accepted.
updateTime string no Output only. CreateTime is the time when the Opportunity was updated.
winLossInfo types.WinLossInfo no

MicrosoftReferralSet fields:

FieldTypeRequiredDescription
connected array<MicrosoftPartnerReferral> no
self MicrosoftPartnerReferral no

SugerOpportunity fields:

FieldTypeRequiredDescription
acceptedDateTime string no AcceptedDateTime is when the partner accepted.
attributionRole structs.SugerAttributionRole no
closedLostReason string no ClosedLostReason is set when the ISV closes the deal as lost.
collaborationContext SugerCollaborationContext no
commissionLifecycle CommissionLifecycle no
commissionPreview SugerCommissionPreview no
commissionsDisabled boolean no Multi-partner attribution (PE-9737): the create API is single-partner (top-level partnerId + attributionRole + revenueShareTerms describe THE partner); additional partners join an existing engagement through the InviteCosellPartners endpoint (SugerCoSellPartnerInput body), each getting its own reseller copy. The per-engagement partner summary for the list table is response-level (ListCosellReferralsResponse.EngagementPartners, keyed by referral id) — never a field on this persisted struct. CommissionsDisabled snapshots, at create time, that the PRM Cosell Commissions feature was NOT in play for this deal — stamped true only when either party lacked the feature (the bilateral both-on check failed). Mirrored identically to both copies and immutable after create, so a later org-config flip never rewrites an in-flight deal. The zero value (false) is the safe default: legacy rows and any un-stamped row read as commissions active. Read via CommissionsActive(); never the raw negative. When true, the commission surface (revenue-share terms, preview, lifecycle) is absent for the deal on both sides (PRM_COSELL_COMMISSIONS).
conversations array<SugerCosellConversation> no Conversations is the in-platform conversation thread surfaced on the co-sell detail page's Activity tab (PE-9488 Component 5). Each entry is one message from a participant. Email replies are NOT stored here — those are queried separately via the auditing / notification-event APIs. This array is for in-platform conversation only. READ-ONLY on the write path: clients receive this on GET responses but MUST NOT modify it via PATCH. Direct changes via this field are rejected by the validator (CONVERSATION_DIRECT_EDIT). To add a message, send `newConversations` instead — the server stamps actor identity and appends. SHARED CROSS-COPY: like CommissionLifecycle, both copies of the engagement carry the same Conversations. The engagement-sync workflow propagates additions to the counterpart row so seller and partner always see the same thread.
createdDateTime string no CreatedDateTime is when this referral was created.
customerInfo SugerCustomerInfo no
dealDetails SugerDealDetails no
dealRole structs.SugerDealRole no
declineReason string no DeclineReason is set when the partner declines.
direction string no Direction is "Outbound" (ISV) or "Inbound" (partner).
engagementId string no EngagementID is a shared UUID linking the ISV's and partner's referral rows.
expirationDateTime string no ExpirationDateTime is when the co-sell expires if not accepted.
externalReferenceId string no ExternalReferenceID is the CRM opportunity ID or any external reference ID.
matchedBuyerId string no MatchedBuyerID is the identity.buyer record auto-matched to this co-sell's end customer by domain (CustomerInfo.Website → buyer info.companyInfo.emailDomain), set on the ISV's (outbound) copy. Drives the §3 CPPO↔co-sell linking and the "End Customer ✓ Matched" surface. Empty when no unambiguous buyer matched (PE-10590 §2).
newConversations array<SugerCosellConversation> no NewConversations is the REQUEST-ONLY append channel for the in- platform conversation thread. Clients submit one or more new messages here on PATCH; the server stamps ID / actor identity / timestamp / source server-side, validates Body is non-empty, appends to Conversations, and clears NewConversations before persisting (the persisted shape never carries this field at the parent level).
nextSteps string no NextSteps is a per-party, free-form field describing the immediate next actions for this co-sell. Either party can edit their own copy; never synced across copies.
onBehalfRegistration SugerOnBehalfRegistration no
revenueShareTerms SugerRevenueShareTerms no
showDealValue boolean no ShowDealValue controls whether THIS copy's owner sees the full deal value. Per-partner and Seller-set (create/invite ShowDealValueToPartner, or the Seller's accept-time choice on reseller-initiated deals), it lives on each reseller (partner) copy like AttributionRole — a sharing control, NOT a commission term, so it exists independently of RevenueShareTerms and survives commissions-disabled deals. Never engagement-synced; server-set only (the generic referral PATCH ignores it). Pointer so nil ("not set" — default visible) is distinct from an explicit false ("hidden"); nil-or-true means visible. The read-path redaction (RedactHiddenDealValue / RedactHiddenDealValueForReferrals) clears the numeric deal-value fields on a Referrer copy when this is false.
stage string no Stage is the deal lifecycle stage: pending, active, in_discovery, proposal_sent, negotiating, on_hold, won, lost.
status string no Status is the per-copy sharing state. Outbound (ISV): draft, sent, closed_won, closed_lost. Inbound (Partner): pending, accepted, declined.
team array<SugerTeamMember> no Team is this copy's own org team members. Each copy holds only its own members; a party sees counterpart teams via the engagement view (EngagementPartner.Team).
type string no Type is the opportunity type: "New Business", "Renewal", "Expansion", "Add On".
updatedDateTime string no UpdatedDateTime is when this referral was last updated.

Responses

200 — OK

Content-Type: application/json · Schema: OperationExecutionDetails

OperationExecutionDetails fields:

FieldTypeRequiredDescription
newWorkflowStarted boolean no
referralId string no ReferralID is the created referral's id, set by the SUGER co-sell create so the caller can chain follow-up calls (e.g. InviteCosellPartners) onto the new engagement without re-querying. Empty elsewhere.
runID string no
slackMirrorWarning string no SlackMirrorWarning is a non-blocking advisory set when a SUGER co-sell console message was saved but could not be mirrored to the partner's Slack channel (no workspace connected, no channel mapped, bot not in the channel, or a transient post failure). Empty when the message mirrored or Slack is not involved. The console surfaces it as a warning toast; the message is always persisted regardless (best-effort mirror).
status string no
workflowID string no

400 — Bad request error

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

FieldTypeRequiredDescription
code ErrorCode no
info object no
message string no

500 — Internal server error

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

FieldTypeRequiredDescription
code ErrorCode no
info object no
message string no

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.