Invoke a journey

covers the snapshot, delays, and cancellation model.

Start a Journey run from the API, then find it by its run ID.

Prerequisites

A published journey with an API trigger

Run a journey

Invoke a journey

Start a run with the invoke endpoint, referencing the journey by its ID or alias in the path.

user_id, or a profile with contact info, for the recipient.
data, optional, matching the trigger schema.
An Idempotency-Key header, so a retried request returns the same run instead of starting a second one.

The response returns a runId.

const journeysInvokeResponse = await client.journeys.invoke('welcome-journey', {
  user_id: 'user_123',
  data: { order_id: 'ORD-9042', order_total: 49.99 },
});

journeys_invoke_response = client.journeys.invoke(
    template_id="welcome-journey",
    user_id="user_123",
    data={
        "order_id": "ORD-9042",
        "order_total": 49.99,
    },
)

curl -X POST https://api.courier.com/journeys/welcome-journey/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "user_id": "user_123",
    "data": { "order_id": "ORD-9042", "order_total": 49.99 }
  }'

journeys_invoke_response = courier.journeys.invoke(
  "welcome-journey",
  user_id: "user_123",
  data: {order_id: "ORD-9042", order_total: 49.99}
)

journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"welcome-journey",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"order_id":    "ORD-9042",
				"order_total": 49.99,
			},
		},
	},
)

JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("welcome-journey")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("order_id", JsonValue.from("ORD-9042"))
            .putAdditionalProperty("order_total", JsonValue.from(49.99))
            .build())
        .build())
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);

$journeysInvokeResponse = $client->journeys->invoke(
  'welcome-journey',
  userID: 'user_123',
  data: ['order_id' => 'ORD-9042', 'order_total' => 49.99],
);

JourneyInvokeParams parameters = new()
{
    TemplateID = "welcome-journey",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "order_id", JsonSerializer.SerializeToElement("ORD-9042") },
        { "order_total", JsonSerializer.SerializeToElement(49.99) },
    },
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);

courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id welcome-journey \
  --user-id user_123 \
  --data '{order_id: ORD-9042, order_total: 49.99}'

With Courier MCP, start my welcome-journey for user_123 with the order details.

Inspect a run

Run inspection is a console view. There is no public endpoint for a run’s step-by-step trace. Take the runId from the invoke response, open the journey’s Logs tab, and search for it. The detail view overlays each node’s outcome on the graph. Click a node to see its step context: input data, profile, conditions evaluated, and output. See for the run states and what each view shows.

Cancel a run

Cancel in-flight runs with the cancel endpoint. Target either a cancelation_token, which cancels every run sharing it, or a single run_id. You set the token in the journey’s settings, so runs carry it from the moment they start.

const cancelJourneyResponse = await client.journeys.cancel({ cancelation_token: 'order-9042-flow' });

cancel_journey_response = client.journeys.cancel(
    cancelation_token="order-9042-flow",
)

curl -X POST https://api.courier.com/journeys/cancel \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelation_token": "order-9042-flow"
  }'

cancel_journey_response = courier.journeys.cancel(cancel_journey_request: {cancelation_token: "order-9042-flow"})

cancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
	CancelJourneyRequest: courier.CancelJourneyRequestUnionParam{
		OfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{
			CancelationToken: "order-9042-flow",
		},
	},
})

CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
    .cancelationToken("order-9042-flow")
    .build();
CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);

$cancelJourneyResponse = $client->journeys->cancel(
  cancelationToken: 'order-9042-flow'
);

JourneyCancelParams parameters = new()
{
    CancelJourneyRequest = new ByCancelationToken("order-9042-flow")
};

var cancelJourneyResponse = await client.Journeys.Cancel(parameters);

courier journeys cancel \
  --api-key "$COURIER_API_KEY" \
  --cancelation-token order-9042-flow

To cancel one run instead, pass the run_id from the invoke response in place of cancelation_token. takes exactly one of the two. Sending both or neither returns 400. It returns 202 with the run and its resulting status:

Status	Meaning
`CANCELED`	The run was active (or already canceled), and is canceled.
`PROCESSED`	The run had already finished. Nothing changed.
`ERROR`	The run had already ended in an error. Nothing changed.

Only active runs are affected, so canceling is idempotent and always safe. A run_id Courier can’t find for your workspace returns 404. To build the token itself, or to cancel from inside a flow, see the .

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Invoke a journey

Prerequisites

Run a journey

Cancel a run

​Prerequisites

​Run a journey

​Cancel a run

Prerequisites

Run a journey

Cancel a run