--- title: "Update journey" method: PATCH path: "/apps/{app_id}/journeys/{id}" --- # Update journey `PATCH /apps/{app_id}/journeys/{id}` ## Request - Base URL: `https://api.onesignal.com` - URL: `https://api.onesignal.com/apps/{app_id}/journeys/{id}` - Auth: none required Apply a partial update to a journey using JSON Merge Patch ([RFC 7396](https://datatracker.ietf.org/doc/html/rfc7396)). Send only the fields you want to change; omitted fields are left unchanged. A `null` value clears a nullable field, and arrays such as `nodes` are replaced wholesale rather than merged element-wise. Set `state` to `active` to activate a draft journey. ## Path parameters - `app_id` string, required - `id` string, required ## Headers - `Authorization` string, required - `Content-Type` string, required ## Request body - object - `name` string: Journey name. - `description` string, nullable: Journey description. Send `null` to clear it. - `audience` union: The journey entry audience. Either a segment-based or event-triggered audience. - object - `kind` 'segment', required - `included_segment_ids` string[]: Segment UUIDs whose users enter the journey. - `excluded_segment_ids` string[]: Segment UUIDs whose users are excluded. - `future_additions_only` boolean: When true, only users who newly match the segment after activation enter the journey. Defaults to false. - object - `kind` 'event_trigger', required - `name` string: Event name that triggers entry, up to 255 characters. - `attributes` array[]: Event attribute matchers, as a list of condition groups. Send a single group whose conditions are AND'd together. More than one group is rejected. - object[] - `key` string, required: Event attribute key. - `operator` 'equal' | 'not_equal' | 'less' | 'less_or_equal' | 'greater_or_equal' | 'greater' | 'is' | 'is_not' | 'exists' | 'not_exists' | 'before' | 'after', required: Comparison operator. - `value` string: Value to compare against. Not required for `exists` and `not_exists`. - `early_exit` JourneyEarlyExit, nullable: Conditions that remove a user from the journey before it completes. At least one rule must be set under `rules`; an early_exit that configures no rule is rejected. Send `null` to remove early exit entirely, or `null` for an individual rule to drop just that rule. - `rules` object - `on_segment` object, nullable - `included_segment_ids` string[]: Exit when the user enters any of these segments. - `when_not_in_audience` boolean, nullable: Exit when the user no longer matches the journey audience. Defaults to false. - `on_session` boolean, nullable: Exit on a new session start. Defaults to false. - `on_event` object, nullable - `name` string, required: Exit when this event occurs. Up to 255 characters. - `tag_on_early_exit` object: Tag key-value pairs applied when a user exits early. - `reentry_rules` JourneyReentryRules, nullable: Controls whether and how soon a user can re-enter the journey. `null` means re-entry is not allowed. - `duration_seconds` integer: Minimum seconds before a user can re-enter. Must be at least `600` (10 minutes). - `schedule` JourneySchedule, nullable: Optional future start and/or stop time. `null` means no scheduled activation. - `start_at` string, nullable: ISO 8601 start time. Use UTC (`Z` or `+00:00`). Must be at least 5 minutes in the future. - `stop_at` string, nullable: ISO 8601 stop time. Use UTC (`Z` or `+00:00`). Must be in the future and later than `start_at`. - `error` string, nullable: Read-only. Present when a scheduling error occurred. - `nodes` JourneyNode[]: Full ordered list of nodes, which replaces the existing graph wholesale. Preserve each node's server-assigned `id` from a prior fetch to keep in-flight users on that node; omit `id` to add a new node. - union: A journey node. The `kind` field selects the shape. Branching nodes (`split_range`, `yes_no`, `wait_until`) nest their sub-graphs inline via `branches[].nodes`. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'wait', required: Holds the user for a fixed duration before continuing. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `duration_seconds` integer: Seconds to hold the user. Minimum `60`, maximum `31556952` (1 year). - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'time_window', required: Holds the user until the next configured time window opens. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `relative_to` 'schedule_in_timezone' | 'last_active_time': `schedule_in_timezone` uses the configured windows; `last_active_time` holds relative to the user's last active time. - `windows` JourneyTimeWindow[]: One or more time windows. A window with no `day_of_week` applies to every day, and is returned in that same day-agnostic form. Required when `relative_to` is `schedule_in_timezone`; must be omitted when it is `last_active_time`, and is absent from responses for those nodes. - `start` JourneyTimePoint - `hour` integer: Hour of day, 0-23. - `minute` integer: Minute of hour, 0-59. Defaults to 0. - `end` JourneyTimePoint - `hour` integer: Hour of day, 0-23. - `minute` integer: Minute of hour, 0-59. Defaults to 0. - `day_of_week` integer: Day of week, 1 = Monday. Omit to apply the window to every day. - `time_zone` string: IANA timezone identifier used when the user's timezone is unavailable. - `use_user_time_zone` boolean: When true, uses the user's timezone if available. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'send_push' | 'send_email' | 'send_sms', required: Sends a message on the given channel using a template. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `template_id` string: UUID of the template to send. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'send_iam', required: Sends an in-app message. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `iam_id` string: UUID of the in-app message to send. - `user_ttl_seconds` integer: Optional time-to-live for the in-app message, in seconds. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'send_webhook', required: Sends a webhook. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `webhook_id` string: UUID of the webhook to send. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'tag', required: Assigns key-value tags to the user. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `assignments` object: Tag key-value pairs to assign. An empty string value removes the tag. Keys are limited to 255 characters and values to 1024. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'split_range', required: Routes users into weighted branches that converge to the next sibling node. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `randomize_on_entry` boolean: When true, assigns each user to a branch at random on entry. Defaults to false. - `branches` JourneyBranch[]: Weighted branches. Between 2 and 25. Weights must sum to 100. Order determines display order. - `id` string: Server-assigned branch identifier. Read-only. - `condition` union: A branch condition. The `kind` field selects the shape. - object - … - object - … - object - … - `weight` number: Branch weight for `split_range` nodes. Weights across a node's branches must sum to 100. - `nodes` JourneyNode[]: Nodes run when this branch is taken, before flow converges to the next sibling node. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'yes_no', required: Routes users into a yes or no branch based on a condition. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `branches` JourneyBranch[]: Exactly two branches. The branch with a `condition` is the "yes" branch; the branch without one is the "no" branch. - `id` string: Server-assigned branch identifier. Read-only. - `condition` union: A branch condition. The `kind` field selects the shape. - object - … - object - … - object - … - `weight` number: Branch weight for `split_range` nodes. Weights across a node's branches must sum to 100. - `nodes` JourneyNode[]: Nodes run when this branch is taken, before flow converges to the next sibling node. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'wait_until', required: Holds the user until any branch condition is met, or an optional expiration timer fires. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `branches` JourneyBranch[]: Condition branches. At least one required, at most 25. Order determines priority. - `id` string: Server-assigned branch identifier. Read-only. - `condition` union: A branch condition. The `kind` field selects the shape. - object - … - object - … - object - … - `weight` number: Branch weight for `split_range` nodes. Weights across a node's branches must sum to 100. - `nodes` JourneyNode[]: Nodes run when this branch is taken, before flow converges to the next sibling node. - `expiration` object, nullable: Optional expiration timer. `null` waits indefinitely. - `duration_seconds` integer: Seconds to wait before the timer fires. Minimum `60`, maximum `31556952` (1 year). - `exits` boolean: When true, the user exits the journey when the timer fires; when false, the user continues to convergence. - `state` 'draft' | 'scheduled' | 'active' | 'archived': Target state. Set `active` to activate a `draft` journey, or `scheduled` together with a future `schedule.start_at` to activate it later. Set `archived` to stop a running journey; archiving is permanent, and later writes return `422 journey-archived`. Only `scheduled` and `processing` journeys can return to `draft`. - `concurrency_key` string, nullable: Optional optimistic-concurrency token. Pass the `concurrency_key` from a prior fetch to reject the update with `409` if the journey changed in the meantime. Omit to skip the check. ## Response `200` 200 - JourneyDetail: Full journey representation returned by the detail and create endpoints. - `id` string: Journey UUID. Read-only. - `app_id` string: UUID of the app the journey belongs to. Read-only. - `name` string: Journey name, up to 300 characters. - `description` string, nullable: Journey description, up to 1024 characters. Defaults to an empty string. - `state` 'draft' | 'scheduled' | 'processing' | 'active' | 'archived': Journey state. Read-only. New journeys are created as `draft`. `processing` is a transient state while an activation is in progress, and `archived` is a journey that has been stopped. Change it through the `state` field on [Update journey](/reference/update-journey). - `created_at` string: ISO 8601 creation time. Read-only. - `updated_at` string: ISO 8601 last-update time. Read-only. - `started_at` string, nullable: ISO 8601 time the journey was activated, or `null`. Read-only. May stay `null` briefly after you set `state` to `active`: activation is enqueued for processing, and `started_at` populates once the journey finishes processing and becomes active. - `archived_at` string, nullable: ISO 8601 time the journey was archived, or `null`. Read-only. - `created_source` string, nullable: Origin of the journey, for example `public_api` or `dashboard`. Read-only. - `audience` union: The journey entry audience. Either a segment-based or event-triggered audience. - object - `kind` 'segment', required - `included_segment_ids` string[]: Segment UUIDs whose users enter the journey. - `excluded_segment_ids` string[]: Segment UUIDs whose users are excluded. - `future_additions_only` boolean: When true, only users who newly match the segment after activation enter the journey. Defaults to false. - object - `kind` 'event_trigger', required - `name` string: Event name that triggers entry, up to 255 characters. - `attributes` array[]: Event attribute matchers, as a list of condition groups. Send a single group whose conditions are AND'd together. More than one group is rejected. - object[] - `key` string, required: Event attribute key. - `operator` 'equal' | 'not_equal' | 'less' | 'less_or_equal' | 'greater_or_equal' | 'greater' | 'is' | 'is_not' | 'exists' | 'not_exists' | 'before' | 'after', required: Comparison operator. - `value` string: Value to compare against. Not required for `exists` and `not_exists`. - `early_exit` JourneyEarlyExit, nullable: Conditions that remove a user from the journey before it completes. At least one rule must be set under `rules`; an early_exit that configures no rule is rejected. Send `null` to remove early exit entirely, or `null` for an individual rule to drop just that rule. - `rules` object - `on_segment` object, nullable - `included_segment_ids` string[]: Exit when the user enters any of these segments. - `when_not_in_audience` boolean, nullable: Exit when the user no longer matches the journey audience. Defaults to false. - `on_session` boolean, nullable: Exit on a new session start. Defaults to false. - `on_event` object, nullable - `name` string, required: Exit when this event occurs. Up to 255 characters. - `tag_on_early_exit` object: Tag key-value pairs applied when a user exits early. - `reentry_rules` JourneyReentryRules, nullable: Controls whether and how soon a user can re-enter the journey. `null` means re-entry is not allowed. - `duration_seconds` integer: Minimum seconds before a user can re-enter. Must be at least `600` (10 minutes). - `schedule` JourneySchedule, nullable: Optional future start and/or stop time. `null` means no scheduled activation. - `start_at` string, nullable: ISO 8601 start time. Use UTC (`Z` or `+00:00`). Must be at least 5 minutes in the future. - `stop_at` string, nullable: ISO 8601 stop time. Use UTC (`Z` or `+00:00`). Must be in the future and later than `start_at`. - `error` string, nullable: Read-only. Present when a scheduling error occurred. - `nodes` JourneyNode[]: Ordered list of journey nodes. - union: A journey node. The `kind` field selects the shape. Branching nodes (`split_range`, `yes_no`, `wait_until`) nest their sub-graphs inline via `branches[].nodes`. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'wait', required: Holds the user for a fixed duration before continuing. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `duration_seconds` integer: Seconds to hold the user. Minimum `60`, maximum `31556952` (1 year). - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'time_window', required: Holds the user until the next configured time window opens. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `relative_to` 'schedule_in_timezone' | 'last_active_time': `schedule_in_timezone` uses the configured windows; `last_active_time` holds relative to the user's last active time. - `windows` JourneyTimeWindow[]: One or more time windows. A window with no `day_of_week` applies to every day, and is returned in that same day-agnostic form. Required when `relative_to` is `schedule_in_timezone`; must be omitted when it is `last_active_time`, and is absent from responses for those nodes. - `start` JourneyTimePoint - `hour` integer: Hour of day, 0-23. - `minute` integer: Minute of hour, 0-59. Defaults to 0. - `end` JourneyTimePoint - `hour` integer: Hour of day, 0-23. - `minute` integer: Minute of hour, 0-59. Defaults to 0. - `day_of_week` integer: Day of week, 1 = Monday. Omit to apply the window to every day. - `time_zone` string: IANA timezone identifier used when the user's timezone is unavailable. - `use_user_time_zone` boolean: When true, uses the user's timezone if available. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'send_push' | 'send_email' | 'send_sms', required: Sends a message on the given channel using a template. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `template_id` string: UUID of the template to send. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'send_iam', required: Sends an in-app message. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `iam_id` string: UUID of the in-app message to send. - `user_ttl_seconds` integer: Optional time-to-live for the in-app message, in seconds. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'send_webhook', required: Sends a webhook. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `webhook_id` string: UUID of the webhook to send. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'tag', required: Assigns key-value tags to the user. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `assignments` object: Tag key-value pairs to assign. An empty string value removes the tag. Keys are limited to 255 characters and values to 1024. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'split_range', required: Routes users into weighted branches that converge to the next sibling node. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `randomize_on_entry` boolean: When true, assigns each user to a branch at random on entry. Defaults to false. - `branches` JourneyBranch[]: Weighted branches. Between 2 and 25. Weights must sum to 100. Order determines display order. - `id` string: Server-assigned branch identifier. Read-only. - `condition` union: A branch condition. The `kind` field selects the shape. - object - … - object - … - object - … - `weight` number: Branch weight for `split_range` nodes. Weights across a node's branches must sum to 100. - `nodes` JourneyNode[]: Nodes run when this branch is taken, before flow converges to the next sibling node. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'yes_no', required: Routes users into a yes or no branch based on a condition. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `branches` JourneyBranch[]: Exactly two branches. The branch with a `condition` is the "yes" branch; the branch without one is the "no" branch. - `id` string: Server-assigned branch identifier. Read-only. - `condition` union: A branch condition. The `kind` field selects the shape. - object - … - object - … - object - … - `weight` number: Branch weight for `split_range` nodes. Weights across a node's branches must sum to 100. - `nodes` JourneyNode[]: Nodes run when this branch is taken, before flow converges to the next sibling node. - object - `id` string: Server-assigned node UUID. Read-only. Returned on reads; sending it on create is rejected with a `400` validation error. - `kind` 'wait_until', required: Holds the user until any branch condition is met, or an optional expiration timer fires. - `client_node_id` string: Optional client-assigned identifier, unique within the journey. Use it to reference this node from elsewhere in the same request (for example as `client_node_id` on an `on_notification_action` condition). Persisted and returned on reads. - `annotation` string: Optional free-text label, up to 1024 characters. Stored and returned as-is with no effect on journey behavior. - `branches` JourneyBranch[]: Condition branches. At least one required, at most 25. Order determines priority. - `id` string: Server-assigned branch identifier. Read-only. - `condition` union: A branch condition. The `kind` field selects the shape. - object - … - object - … - object - … - `weight` number: Branch weight for `split_range` nodes. Weights across a node's branches must sum to 100. - `nodes` JourneyNode[]: Nodes run when this branch is taken, before flow converges to the next sibling node. - `expiration` object, nullable: Optional expiration timer. `null` waits indefinitely. - `duration_seconds` integer: Seconds to wait before the timer fires. Minimum `60`, maximum `31556952` (1 year). - `exits` boolean: When true, the user exits the journey when the timer fires; when false, the user continues to convergence. - `concurrency_key` string: Opaque optimistic-concurrency token. Read-only. Pass it back on update to guard against overwriting a concurrent change (`409 journey-stale`). Send it back exactly as read from this response; do not construct or parse it. ## Other responses - `400`: 400 - `403`: 403 - `404`: 404 - `409`: 409 - `422`: 422 - `429`: Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying. ## Changes - **2026-11-03** `36dfd39b1be3`: 1 info - endpoint added [Operation history](https://skmtc.dev/onesignal/apis/api-onesignal-com/changes/apps/:app_id/journeys/:id/patch.md) --- [API](https://skmtc.dev/onesignal/apis/api-onesignal-com.md) - [All operations](https://skmtc.dev/onesignal/apis/api-onesignal-com/llms.txt) - [OpenAPI document](https://skmtc.dev/onesignal/apis/api-onesignal-com/revisions/36dfd39b1be3?raw)