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. Send the target `state` — the matching action is derived from the (current, target) pair. `referralId` is the caller's own referral, and the payee copy that holds the commission is resolved server-side. Actor identity is taken from the auth context. These are the only transitions a client may request; every other pair is rejected with 400: - PENDING -> APPROVED — Seller approves the commission. - APPROVED -> PAYMENT_SENT — Seller marks payment sent. - PAYMENT_SENT -> CONFIRMED — Partner confirms receipt. - PAYMENT_SENT -> APPROVED — Partner rejects the payment; the server records PAYMENT_REJECTED and reverts to APPROVED in one write, so send APPROVED, not PAYMENT_REJECTED. - CONFIRMED -> CLAWED_BACK — Seller claws back, and only while the clawback window is open. PENDING_UPDATE_APPROVAL is not a target you send. It is entered by ProposeCommissionUpdate and left by sending `action` = approve_update or reject_update (Partner only), which returns the commission to the state it held before the proposal. A Seller must also send `partnerOrganizationId` naming which partner's commission is being acted on; a partner acting on its own commission omits it. To change the commission terms themselves, use ProposeCommissionUpdate — this operation moves states, it does not edit terms.

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, and are the Partner's answer to a Seller's ProposeCommissionUpdate). 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). CONDITIONALLY REQUIRED: mandatory when the caller is the Seller, and ignored when the caller is the partner acting on its own commission. The condition cannot be expressed in the schema, so the field is not listed as unconditionally required — a Seller omitting it gets 400.
`state`	string	yes	State is the target lifecycle state. Always required. The action is derived from the (current → target) pair, and only these pairs may be requested by a client: PENDING→APPROVED (Seller), APPROVED→PAYMENT_SENT (Seller), PAYMENT_SENT→CONFIRMED (Partner), PAYMENT_SENT→APPROVED (Partner; recorded as PAYMENT_REJECTED then reverted to APPROVED), and CONFIRMED→CLAWED_BACK (Seller, only while the clawback window is open). Any other pair is rejected with 400.

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

Example

Generated from this operation's schema. Values are placeholders — substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X PATCH 'https://api.suger.cloud/org/{orgId}/cosell/referral/{referralId}/commission' \
  -H 'Authorization: Bearer $SUGER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "state": "APPROVED"
}'

Response — 200

{
  "newWorkflowStarted": true,
  "referralId": "01H0000000000000000000",
  "runID": "01H0000000000000000000",
  "slackMirrorWarning": "string",
  "status": "string",
  "workflowID": "01H0000000000000000000"
}

Error — 400

{
  "code": "InternalServerError",
  "message": "string"
}

View as Markdown · Interactive API reference

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