Getting Started with Onboarding Walkthrough

The Onboarding Walkthrough API lets you track an affiliate's progress through their 11-step onboarding checklist. Affiliates can complete steps individually, skip steps, skip the entire walkthrough, or start over from the beginning.

Overview

Each affiliate has a walkthrough state that includes:

• Overall status: not_started → in_progress → completed or skipped
• Current step: Points to the next incomplete step (useful for UI navigation)
• Step history: Each of the 11 steps has its own status (not_started, completed, skipped) and timestamps
• Retake count: Incremented each time the walkthrough is reset

The walkthrough is lazy-initialized—if an affiliate has never touched it, the API returns a fresh structure with all steps in not_started status.

Step progression

The walkthrough has 11 sequential steps. Steps do not need to be completed in order; an affiliate can complete step 5 before step 1 if they wish. The currentStep field automatically advances to the next incomplete step after each action.

Actions and state transitions

Complete a step

PATCH /v2/onboardingWalkthrough
Content-Type: application/json

{
  "action": "complete_step",
  "step": 3
}

Marks step 3 as completed. If the overall status was not_started, it transitions to in_progress. If all 11 steps are now in a terminal state (completed or skipped), the overall status becomes completed.

Skip a step

PATCH /v2/onboardingWalkthrough
Content-Type: application/json

{
  "action": "skip_step",
  "step": 3
}

Marks step 3 as skipped without completing it. Like complete_step, it advances currentStep and may transition the overall status to completed if all steps are terminal (though the overall status would be completed only if at least one step was completed; pure skip-all sets status to skipped).

Skip the entire walkthrough

PATCH /v2/onboardingWalkthrough
Content-Type: application/json

{
  "action": "skip"
}

Bulk-skips all remaining not_started steps in one operation. Sets the overall status to skipped immediately. Does not require a step parameter.

Retake the walkthrough

PATCH /v2/onboardingWalkthrough
Content-Type: application/json

{
  "action": "retake"
}

Resets all 11 steps to not_started, clears the completed and skipped timestamps, sets overall status back to not_started, and advances currentStep to 1. The retakeCount increments. The original startedAt timestamp is preserved to track when the affiliate first touched the walkthrough.

Checking progress

GET /v2/onboardingWalkthrough

Returns the full walkthrough state, wrapped in the standard {success, data} envelope:

{
  "success": true,
  "data": {
    "status": "in_progress",
    "currentStep": 4,
    "retakeCount": 0,
    "startedAt": "2026-06-15T10:00:00Z",
    "completedAt": null,
    "skippedAt": null,
    "steps": [
      {
        "stepNumber": 1,
        "status": "completed",
        "completedAt": "2026-06-15T10:05:00Z",
        "skippedAt": null
      },
      {
        "stepNumber": 2,
        "status": "skipped",
        "completedAt": null,
        "skippedAt": "2026-06-15T10:06:00Z"
      },
      {
        "stepNumber": 3,
        "status": "completed",
        "completedAt": "2026-06-15T10:10:00Z",
        "skippedAt": null
      },
      {
        "stepNumber": 4,
        "status": "not_started",
        "completedAt": null,
        "skippedAt": null
      }
      // ... steps 5–11 ...
    ]
  }
}

The walkthrough fields (status, currentStep, steps, etc.) are under data — reading them from the top level of the response will return undefined.

Use this to:

• Display the affiliate's current onboarding progress
• Show which steps have been completed, skipped, or are pending
• Determine whether to show onboarding prompts or guides

Common patterns

Offer a "skip all" button

If an affiliate wants to dismiss onboarding entirely, call:

PATCH /v2/onboardingWalkthrough
Content-Type: application/json

{
  "action": "skip"
}

This sets all remaining steps to skipped and transitions the overall status to skipped.

Allow a second chance (retake)

If an affiliate marked steps complete but now wants to redo the walkthrough, send:

PATCH /v2/onboardingWalkthrough
Content-Type: application/json

{
  "action": "retake"
}

This resets all steps to not_started and increments retakeCount (useful for analytics).

UI: highlight the next incomplete step

After each progress update, the response includes currentStep. Use this in the UI to:

• Highlight the next step the affiliate should complete
• Auto-scroll or focus that step when the page loads
• Disable or hide steps that have already been acted on

Batch completions (multi-step actions)

If your UI lets affiliates complete multiple steps at once (e.g., "complete setup" marks steps 1–5 done), make multiple PATCH requests in sequence, one per step:

# Step 1
PATCH /v2/onboardingWalkthrough
{ "action": "complete_step", "step": 1 }

# Step 2
PATCH /v2/onboardingWalkthrough
{ "action": "complete_step", "step": 2 }

# ... etc

Alternatively, batch them client-side and reflect the final state after the last request.

Error handling

Authentication

All endpoints require an affiliate token. Include it in the Authorization header or as a query parameter access_token.