> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargerdojo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Author a custom journey

> The custom journey JSON shape, the knobs that matter, and how to import, run, and save a journey you wrote by hand or generated from CI.

A **custom journey** is a charging journey described as JSON: the same thing the
Charging Journeys builder produces, written down so a human or an agent can version
it, diff it, and replay it from CI. Import one and it opens ready to run: a
template-shaped file opens with every knob restored, and a file with its own
hand-authored action list opens with that list shown, its values editable in the
builder (more on the difference below). Either way it streams evidence and lands a
report exactly like a catalogue journey.

The fastest way to get a valid file is **Download sample** on the Charging Journeys
page. It exports a ready-to-run custom journey for your selected target. Edit that, or
write one from the shape below.

## The shape

```json theme={null}
{
  "schemaVersion": 1,
  "journey": "first-successful-charge",
  "roleUnderTest": "EMSP",
  "journeyPack": "core-charging",
  "ocpiVersion": "2.2.1",
  "coverageDepth": "happy-path",
  "clock": { "mode": "accelerated", "durationSeconds": 3000 },
  "session": {
    "cadenceSeconds": 300,
    "jitterSeconds": 0,
    "strategy": "put-and-patch",
    "updates": ["kwh", "total_cost", "status", "charging_periods"]
  },
  "catalogue": { "locationUpdates": true, "tariffUpdates": true },
  "completion": { "cdrDelaySeconds": 300 },
  "contract": { "cdrWithinSeconds": 600 },
  "disturbances": [],
  "seed": "204"
}
```

## The knobs that matter

* **`journey`**: the template the custom journey starts from (e.g. `first-successful-charge`).
  It selects the story; an unknown id falls back to the recommended journey.
* **`ocpiVersion`** and **`targetId`** are advisory in the file. On import the builder
  runs the journey against whichever target you have selected, so a sample from one
  target still runs against another, and you do not need a real `targetId` to share a
  file.
* **`clock.mode`**: `accelerated` compresses a session into seconds; `real` runs it at
  wall-clock cadence for long-session testing.
* **`session.cadenceSeconds`** and **`jitterSeconds`**: how often meter updates are
  pushed, and how irregular they are (`jitterSeconds` above 0 means irregular).
* **`session.updates`**: which fields each update carries (`kwh`, `total_cost`,
  `status`, `charging_periods`).
* **`disturbances`**: faults injected mid-journey to prove the endpoint fails safely
  (e.g. `skip_intermediate_update`, `duplicate_full_put`, `delay_cdr`).
* **`coverageDepth`**: `happy-path`, `edge-cases`, or `adversarial`.
* **`seed`**: makes a run reproducible; keep it stable to replay the same story.

Unknown or malformed fields fall back to sensible defaults, so a partial file still
imports and simply uses the defaults for anything you left out. One exception: a file
that spells out its own timed `actions` list carries those **hand-authored actions**
into the builder too, as the timeline the file wrote rather than the knob editor
above. The Configure step shows each action's time, kind, and values, in the order
the file lists them. The run itself executes each action at its own time, not the
list order, so keep the list chronological if you want the two to match. Click any
value to change it in place: the builder shows what the value must be and, where an
OCPI version defines the field, the spec file it comes from. Timing comes straight
from the file; you can still change the endpoint, the clock, and the seed, and the
run streams and grades exactly like any other custom journey. To change an action's
kind, its time, or the order of the list, edit the JSON and re-import.

A second exception: a file that names `journey: 'custom'` but lists no actions is
refused, with a message, rather than imported and silently emptied. That intent
(a custom journey) is not something the importer discards on your behalf.

## Import, run, and save

1. On **Charging Journeys**, choose **Import scenario JSON** and pick your file, or
   **Download sample** to start from a working one.
2. The custom journey opens in the builder on the **Configure** step with your knobs
   applied. Adjust anything, then **Preview** to compile the plan.
3. **Start the run.** It streams live and lands a graded report in **Runs**, stored on
   your account, replayable and runnable from CI with the same JSON.

You can annotate a working copy with `//` comments and trailing commas; the importer
strips them. The API and CI expect strict JSON.

See also [Run a charging journey](/guide/run-a-charging-journey) for the run, follow,
and recovery flow.