Apply a commission lifecycle action

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

Advance a SUGER co-sell's commission to its next state once the deal is Won: APPROVED, PAYMENT_SENT, PAYMENT_REJECTED, CONFIRMED or CLAWED_BACK. Send the target `state` — the matching action is derived from the current and target pair. `referralId` is the caller's own referral, and the payee copy that holds the commission is resolved server-side. A Seller must also send `partnerOrganizationId` naming which partner's commission is being acted on; a partner acting on its own commission omits it. Actor identity is taken from the auth context. To change the commission terms themselves, use ProposeCommissionUpdate; set `action` to approve_update or reject_update here only to resolve a terms change that is already pending.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`referralId`	path	string	yes	Cosell Referral ID

Request Body

Required. Content-Type: application/json · Schema: UpdateCommissionLifecycleRequest

UpdateCommissionLifecycleRequest fields:

Field	Type	Required	Description
`action`	string	no	Action, when set, selects a post-Won terms-update transition that the (current → target) state can't disambiguate on its own: "approve_update" or "reject_update" (both resolve PENDING_UPDATE_APPROVAL → PriorState). Left empty for the ordinary state-driven transitions, whose action is inferred.
`note`	string	no
`partnerOrganizationId`	string	no	PartnerOrganizationID names which partner's commission a Seller is acting on (each partner in an engagement has its own commission). Required for a Seller action; ignored when the caller is the reseller (they only have their own commission).
`state`	string	no

Responses

200 — OK

Content-Type: application/json · Schema: OperationExecutionDetails

OperationExecutionDetails fields:

Field	Type	Required	Description
`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 / invalid transition

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

Field	Type	Required
`code`	ErrorCode	no
`info`	object	no
`message`	string	no

500 — Internal server error

Content-Type: application/json · Schema: ErrorResponse

ErrorResponse fields:

Field	Type	Required
`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.