# 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 | Description |
| --- | --- | --- | --- |
| `code` | ErrorCode | no |  |
| `info` | object | no |  |
| `message` | string | no |  |

### 500 — Internal server error

Content-Type: `application/json` · Schema: `ErrorResponse`

**`ErrorResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | ErrorCode | no |  |
| `info` | object | no |  |
| `message` | string | no |  |

---

Interactive API reference: https://doc.suger.io/api/