# Journey

> Load when the client wants to create, edit, or manage a CDP customer journey. Use for building journey YAML with segments, activations, and stage steps, modifying journey stages or flow logic (decision points, condition waits, A/B tests), or pushing journey changes to Treasure Data. Also load when the client wants to analyze journey performance, query journey tables, create journey dashboards, or generate journey action reports.

- Skill: `treasure-data/journey` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds add treasure-data/journey`
- Raw SKILL.md: https://api.skillmd.com/api/skills/treasure-data/journey/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: treasure-data (https://skillmd.com/u/treasure-data)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/treasure-data/journey

---


# tdx Journey - CDP Journey Orchestration

## Quick Reference

| Task | Guide |
|------|-------|
| Build journey YAML | Follow the [5 steps](#build-process) below |
| Analyze journey performance | Follow the [analysis workflow](#analysis-workflow) below |
| Create a new journey version | Follow the [version creation](#version-creation) below |

## Analysis Workflow

**You MUST read the reference files** using the Read tool before doing anything else. These contain domain-specific data models and workflows that are NOT guessable.

1. **Read `references/analyze.md`** (MANDATORY) — 5-phase analysis workflow
2. **Read `references/journey-table.md`** (MANDATORY) — journey table data model, column naming, state logic
3. Follow the phases in `references/analyze.md` in order

## Version Creation

**You MUST read `references/version-create.md`** using the Read tool before doing anything else. Version creation clones the existing journey — do NOT rebuild from scratch, but refer to Build Process templates for correct YAML syntax.


## Build Process

Build journey YAML **incrementally** through 5 steps.

**FIRST: Create a TODO list** with one task per step before starting any work. This ensures you follow the step-by-step process and do not skip ahead. Mark each task as in_progress when you start it and completed when done.

**CRITICAL RULES:**
- **You MUST read the template file** for each step using the Read tool before doing anything else. The templates contain required discovery commands and instructions. Do NOT write YAML from memory.
- Complete steps in order, one at a time. NEVER skip or combine steps.

**Workflow for EACH step:**
1. **Read the template file** (MANDATORY — use Read tool on the template path)
2. **Run the discovery commands** listed in the template (MANDATORY — do NOT guess values)
3. Ask the client for the required information (if not already provided)
4. **Show the design/plan and get client confirmation** — this is the ONE confirmation point per step
5. Write the updated YAML to the journey file
6. **Immediately proceed to the next step** — do NOT ask "shall we proceed?" or "please review". The client already confirmed in step 4.

**File location**: `./segments/(parent-segment-name)/journey-name.yml`

## Prerequisites


```bash
tdx sg pull "Parent Segment Name"   # Pull parent segment data (sets context)
```

## Commands

```bash
tdx journey pull                             # Pull all journeys to YAML
tdx journey pull path/to/journey.yml         # Pull specific journey
tdx journey validate path/to/journey.yml     # Validate YAML locally (offline)
tdx journey push --dry-run                   # Preview changes against API
tdx journey push --yes                       # Push journey
tdx journey push path/to/journey.yml --yes   # Push specific journey
tdx journey pause "Journey Name"             # Pause running journey
tdx journey resume "Journey Name"            # Resume paused journey
tdx journey view "Journey Name" --include-stats
```

## The 5 Steps

| Step | What to do | Template |
|------|-----------|----------|
| 1 | Criteria segments (goal, entry/exit, milestone) | `templates/step1-criteria.yml` |
| 2 | Decision point branches + condition wait segments | `templates/step2-decisions.yml` |
| 3 | Activations | `templates/step3-activations.yml` |
| 4 | Journey structure + stage steps (one stage at a time) | `templates/step4-journey.yml` |
| 5 | Validate and push | (see below) |

**Start with Step 1**: Read `templates/step1-criteria.yml` and follow the instructions inside.

### Step 5: Validate, Preview, and Push

After completing Step 4:

**1. Validate**
```bash
tdx journey validate path/to/journey.yml   # Local validation
tdx journey push --dry-run                 # API validation
```
Fix any errors before proceeding.

**2. Preview (MANDATORY before push)**

Call `preview_journey` with the YAML file path. Ask the client to verify the visual flow structure (stage names, branch paths, merge and end points) before pushing. Do NOT skip this step.

**3. Push**
```bash
tdx journey push path/to/journey.yml --yes
```

Use TD Console "Simulation Mode" to validate before launching.

## Segment References

- **Embedded** (recommended): `segment: my-segment` (defined in `segments:` section — always create new segments this way)
- **External ref**: `segment: ref:Segment Name` (references a journey-type segment from another journey)

### `ref:` limitations

`ref:` can ONLY reference **journey-type segments (kind=3)** — segments that were created by another journey's push. It does NOT work with regular child segments created via `tdx sg push`.

**Valid workflow for `ref:`:**
1. `tdx journey pull "Existing Journey"` → segments appear as `ref:SegmentName`
2. Create a new journey YAML referencing those same segments via `ref:`
3. `tdx journey push` → works because the referenced segments are already journey-type

**Do NOT** search for existing batch segments with `tdx sg list` and reference them with `ref:`. This will resolve the ID but the journey API will reject it.

**When in doubt, use embedded segments.** They are always safe and give you full control over the rule definition.

## Goal Target (Optional)

Goal is defined per version entry inside `journeys`. When met, optionally route users to another journey:

```yaml
journeys:
  - state: draft
    goal:
      name: Made Purchase
      segment: purchasers
      target:                    # Optional: jump when goal met
        journey: Post-Purchase Journey
        stage: Thank You
    stages:
      # ...
```

## Wait Step Options

```yaml
# Duration wait
- type: wait
  name: Wait 7 Days
  next: Next Step
  with:
    duration: 7
    unit: day                          # day | week

# Condition wait (NO top-level next: — paths inside condition)
- type: wait
  name: Wait for Purchase
  with:
    condition:
      segment: made-purchase
      next: Thank You Path
      timeout:
        duration: 14
        unit: day
        next: Timeout Path
```

Other wait options: `wait_until: "2025-04-01"` | `days_of_week: ["monday", "wednesday", "friday"]`

**API constraint**: A wait step must follow every activation step (place after merge if activation → merge).

**Limits**: Max 8 stages (local), 120 events/journey, 70 events/stage, 30 versions (API)

## Best Practices

- **Frequency capping**: Use wait steps between activations to control message frequency. Avoid sending more than 1 message per day per channel.
- **Consent management**: Include opt-in/subscription status in entry_criteria or exit_criteria segments (e.g., `email_opt_in = true`).
- **Suppression**: Use exit_criteria to remove users who should stop receiving messages (e.g., recent purchasers, open support tickets).
- **Reentry mode**: Use `no_reentry` for one-time campaigns, `reentry_unless_goal_achieved` for ongoing programs, `reentry_always` for recurring triggers.

## Related Skills

- **connector-config** - `connector_config` fields for activations
- **validate-journey** - Validation rules reference
- **segment** / **validate-segment** - Segment rule syntax
- **parent-segment** - Parent segment management