# Complete or reopen a journey step

`POST https://api.suger.cloud/ai/org/{orgId}/prm/journeyAssignment/{assignmentId}/step/{stepId}/transition`

Set the status of one step of a journey assignment, sent as `to`: DONE completes it, NOT_STARTED or IN_PROGRESS reopens it. The assignment's progress and status are recomputed, and the updated assignment is returned. Completing a step emails the assigning user and the partner's champion contact. Completing the last required step completes the journey and, when the journey has a tier outcome, moves the partner to that tier. A linked task follows the step (DONE to COMPLETED, IN_PROGRESS to IN_PROGRESS, NOT_STARTED to OPEN) when this organization is allowed to move it.

`assignmentId` is the `id` of a row from ListJourneyAssignments whose `organizationId` is this organization, and `stepId` the `id` of one of its `steps`. In a sequential journey a step cannot be completed while an earlier required step is open (409), and an ARCHIVED journey's steps cannot change (400).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `assignmentId` | path | string | yes | Assignment ID |
| `stepId` | path | string | yes | Step ID |

## Request Body

Required.

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

**`TransitionJourneyStepRequest`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `to` | string | no |  |

## Responses

### 200 — OK

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

**`JourneyAssignmentDetail`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `archivedAt` | string | no |  |
| `assignedAt` | string | no |  |
| `assignedByUserId` | string | no |  |
| `completedAt` | string | no |  |
| `createTime` | string | no |  |
| `description` | string | no |  |
| `estimatedDays` | integer | no |  |
| `id` | string | no |  |
| `lastUpdateTime` | string | no |  |
| `name` | string | no |  |
| `organizationId` | string | no |  |
| `outdated` | boolean | no |  |
| `partnerName` | string | no | PartnerName is the assignee partnership's display name (Info.Name), populated by the org-wide list so each journey row shows its assignee without a separate partners fetch. Empty when not resolved. |
| `partnershipId` | string | no |  |
| `progress` | JourneyProgress | no |  |
| `sequential` | boolean | no |  |
| `stalled` | boolean | no |  |
| `status` | string | no |  |
| `steps` | array<JourneyStepView> | no |  |
| `templateId` | string | no |  |
| `templateVersion` | integer | no | TemplateVersion is the template revision this assignment was built from; Outdated is true when the template has since advanced past it (drift). |
| `tierOutcome` | string | no |  |
| `tierOutcomeInfo` | PartnerTier | no |  |
| `version` | integer | no |  |
| `viewerPartnershipId` | string | no | ViewerPartnershipID is the partnership row the CURRENT viewer should open to reach the relationship's detail page. For the owning ISV it's the same as PartnershipID; for a partner-side read it's the partner's OWN mirror row (org = partner, partner_org_id = ISV), since the partner can't open the ISV-owned PartnershipID. Empty when no viewer-side row exists. |
| `kind` | string | no | — TIER on a "Path to <tier>" journey. |
| `renewalDeadline` | string | no | — set while this tier journey renews the partner's tier. |
| `renewalFiscalYearStart` | string | no | — the fiscal-year start a renewal last restarted this tier journey for; kept once the renewal is done (renewalDeadline is then cleared). Absent if the journey was never renewed. |

**`JourneyProgress`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed` | integer | no |  |
| `completedRequired` | integer | no |  |
| `total` | integer | no |  |
| `totalRequired` | integer | no |  |

**`JourneyStepView`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agreementId` | string | no | AgreementID links a SIGN_AGREEMENT step to the partner_agreement created for it at assign time, so executing THAT agreement completes THIS step. Empty when auto-create was skipped/failed — then the step completes on any executed agreement (the pre- match-by-type fallback). |
| `completedAt` | string | no |  |
| `completedByUserId` | string | no |  |
| `ctaLabel` | string | no |  |
| `ctaUrl` | string | no |  |
| `description` | string | no |  |
| `dueAt` | string | no |  |
| `dueRemindersSent` | array<integer> | no | DueRemindersSent lists the EXPIRE_SOON.JOURNEY lead-day thresholds (e.g. 7, 1) already reminded for this step, so the daily journey cron sends each threshold's reminder at most once. Cleared when the step is reopened via applyStepStatus (a re-completion cycle re-arms the reminders only if the due date is still ahead). |
| `id` | string | no |  |
| `internalNotes` | string | no |  |
| `locked` | boolean | no |  |
| `order` | integer | no |  |
| `refId` | string | no | course / certificate id |
| `refName` | string | no | RefName is the display name of the referenced course / certificate, snapshotted at assign time so the partner (a different org) can show it without resolving the ISV's course / certificate ids. |
| `required` | boolean | no |  |
| `status` | string | no |  |
| `targetCount` | integer | no | REGISTER_DEAL EARN_CERTIFICATION with People needed (the people). |
| `taskId` | string | no | CUSTOM_TASK linked partnership_task |
| `taskNames` | array<string> | no | TaskNames lists the task titles from the referenced task template (CUSTOM_TASK), snapshotted at assign time so both views can show every task the template defines, not just the first. |
| `templateStepId` | string | no | TemplateStepID links back to the JourneyTemplateStep.ID this step was snapshotted from, so a reassign can match progress across template edits. Empty for assignments created before this field existed. |
| `title` | string | no |  |
| `type` | string | no |  |
| `section` | string | no | — the step's heading (Delivery, Revenue, Marketing...). |
| `autoComplete` | boolean | no | — a metric step; it completes itself and nobody ticks it. |
| `dealValue` | JourneyDealValueConfig | no |  |
| `marketingPoints` | JourneyMarketingPointsConfig | no |  |
| `progress` | JourneyStepProgress | no |  |

**`PartnerTier`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `benefits` | string | no | Benefits is a freeform benefits line shown to partners. |
| `color` | string | no | Color is the badge color as a hex string, e.g. "#d4a017". |
| `description` | string | no | Description is shown to partners in the portal. |
| `id` | string | no | ID is a stable identifier referenced by PartnershipInfo.PartnerTier. Assignments survive tier renames/recolors because they key on ID. |
| `name` | string | no | Name is the display label, e.g. "Gold". |

**`JourneyDealValueConfig`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `measure` | string | no | VALUE (default, the deal value in the period) \| COUNT (the number of deals, all time). |
| `atLeast` | number | no |  |
| `dealKinds` | array<string> | no | SOURCED \| CO_SOLD \| CLOSED_WON. |
| `dateField` | string | no | CLOSE \| REGISTERED \| CREATED. |
| `period` | string | no | FISCAL_YEAR \| FISCAL_QUARTER \| TRAILING_12_MONTHS \| CUSTOM. |
| `start` | string | no |  |
| `end` | string | no |  |
| `source` | string | no | FOURS \| SALESFORCE. |
| `salesforce` | JourneySalesforceDealValue | no |  |

**`JourneyMarketingPointsConfig`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `points` | integer | no |  |
| `period` | string | no |  |

**`JourneyStepProgress`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `current` | number | no |  |
| `target` | number | no |  |
| `windowStart` | string | no | Start of the counting period (inclusive). |
| `windowEnd` | string | no | End of the counting period (exclusive) — the window is [windowStart, windowEnd). |
| `computedAt` | string | no |  |
| `error` | string | no |  |

**`JourneySalesforceDealValue`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | no | Always Opportunity (omitted means Opportunity). |
| `valueField` | string | no |  |
| `dateField` | string | no |  |
| `filters` | array<JourneySalesforceFilter> | no |  |

**`JourneySalesforceFilter`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | string | no |  |
| `operator` | string | no | EQ \| NEQ. |
| `value` | string | no |  |

### 409 — Step locked

Content-Type: `application/json`

## Example

_The request bodies are this operation's documented examples; the response and error bodies are generated from its schema. Substitute your own ids, and set `SUGER_TOKEN` to a bearer token from the [OAuth client-credentials exchange](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X POST 'https://api.suger.cloud/ai/org/{orgId}/prm/journeyAssignment/{assignmentId}/step/{stepId}/transition' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "DONE"
}'
```

### Response — 200

```json
{
  "archivedAt": "string",
  "assignedAt": "string",
  "assignedByUserId": "01H0000000000000000000",
  "completedAt": "string",
  "createTime": "2026-01-31T12:00:00Z",
  "description": "string",
  "estimatedDays": 1,
  "id": "01H0000000000000000000",
  "lastUpdateTime": "2026-01-31T12:00:00Z",
  "name": "Acme Corp",
  "organizationId": "01H0000000000000000000",
  "outdated": true
}
```

### Error — 409

```json
"string"
```

---

API reference: https://doc.fours.com/api/
