How a workflow runs: triggers, steps and runs
A workflow is the plan: one trigger and its steps. A run is one execution of that plan for one event. This page follows an event from the moment it arrives to the finished run.
From event to run
- An event arrives. Shopify reports a change, a schedule is due, another system calls the workflow's webhook URL, or you press Run now.
- The app finds the workflows for it. Only workflows that are turned on and use this trigger are considered.
- The trigger filter decides. If you ticked Only start for some events, the rules are checked. An event the filter rejects starts nothing and does not count against your plan. See Trigger filters.
- Loop protection checks the cause. If the event is the echo of a change this workflow made itself a moment ago, the run is not started. See Loop protection.
- The run is counted. One run uses one run of your plan, however many steps it has.
- The steps run in order, starting at the first step under the trigger. Each step's result is kept, so later steps can read it.
- The run ends as Completed or Failed, and appears in the Run history.
What a step sees
Every step can read:
event- the trigger's data:event.topic,event.payload, and for change triggersevent.changes.steps- the results of the steps that ran before it, for examplesteps.request_1.output.body.vars- the workflow's variables.secrets- your secrets, by name.loop- inside a Repeat for each: the current item and its position.shopandrun- your store's domain, the run's id and whether it is a test.
See Variables and the variable picker.
Run statuses
| Status | Meaning |
|---|---|
| Queued | The run is accepted and starts in a moment |
| Running | Steps are being executed |
| Waiting | The run reached a Wait step, or was started with a delay, and continues when the time is up |
| Completed | Every step on the path finished |
| Failed | A step failed, or a Fail the run step ended it |
| Not started | Loop protection or the plan limit stopped the run before any step ran. The run says why |
| Cancelled | You stopped a debug session, or a queued or waiting run was cancelled over the API |
When a step fails
A failure that is temporary, such as a busy server, is tried again automatically. Any other failure fails the step, and the run ends as Failed at that step. Later steps do not run. Inside a Repeat for each you can choose to go on with the next item instead. See Automatic retries and Repeat for each.
A run that was interrupted while it was running is marked as Failed and is not run again, because some of its steps may already have changed something.
Waits keep the workflow as it was
A run that waits, for an hour or for thirty days, continues with the workflow as it was when the run started, even if you edit the workflow in the meantime. New runs use the new version.
Limits of one run
- A workflow can have up to 100 steps.
- One run executes up to 1,000 steps, repeated ones included.
- A Repeat for each handles up to 500 items. A longer list fails the step; it is never cut short.
- A Wait can be up to 90 days.
- A run has about 8 minutes of working time between waits. A loop that runs out of time fails with a message that says how many items it finished.
What counts against your plan
Real runs count: runs started by an event, a schedule, an incoming webhook, another workflow, Run now or the Developer API. Test runs, debug sessions, events rejected by the trigger filter and runs that were not started are free. See Plans, runs and extra runs.