How Workflows work

Workflows provides a visual builder in the Stripe Dashboard, to help you automate tasks and processes by defining a series of actions that happen sequentially. Workflows is ideal for multi-step processes and is compatible across multiple Stripe products, allowing you to streamline processes, enforce business rules, and reduce manual effort.

Each workflow consists of a trigger and a series of steps that run in order. A step is either an action or a condition. A workflow is made up of the following components:

Workflows automate tasks by running a series of actions sequentially based on triggers and conditions. If multiple workflows share the same trigger event, each workflow runs independently, following its own defined steps and business logic.

Active versus inactive workflows

You can activate, deactivate, or delete workflows. After you deactivate a workflow, Stripe considers it as inactive and it can no longer respond to triggers. You can reactivate an inactive workflow at any time. You can maintain up to 50 active workflows at a time and have a combined total of 50 active and inactive workflows.

If you have 50 workflows, you can’t create another one. If you have 50 active workflows and want to activate a new one, you must first deactivate an existing active workflow.

Versioning

Each time you activate a workflow, Stripe saves a numbered version of its configuration. You can also annotate each version with a description explaining the reason for the change.

Over time, this builds a clear, shared record of updates across your team. The workflow itself becomes a central repository of contextual information.

You can view all past versions in the workflow’s history.

If you need to revert to a previous version, you can restore the configuration back into the Workflow editor and reactivate it.

Drafts

Draft mode provides you a separate workspace for editing your active workflow. To use draft mode, click Save draft in the editor.

This feature allows you to modify conditions, add steps, and reorganize branches without impacting the live version. By separating the iteration process from production logic, you can refine your workflow safely and at your own pace before deployment.

Triggers

Workflows are started by Stripe API events, by a recurring schedule, or on demand. For details on each type, see Triggers. Each workflow has one trigger, and it’s always the first step of a workflow. The trigger provides data to the workflow: either the event payload (for event triggers) or custom input data (for on-demand triggers). This data is passed into the workflow so subsequent steps can use it. After a trigger fires and provides its data, the workflow moves on to perform its actions using that data. Workflows with a recurring schedule trigger start without input data.

If you want to trigger a workflow related to a customer, these triggers can apply to you:

If you’re using Stripe to accept payments (such as Stripe Checkout or the CheckoutSessions API), these triggers can apply to you:

If you’re using Stripe to accept async payment methods, such as bank transfers and BNPL (which requires additional time to confirm payment details), these triggers can apply to you:

If you want to trigger a workflow based on the outcome of money movement or on whether a charge succeeds or fails, the following triggers can apply to you. Most Stripe integrations use Checkout or PaymentIntent events (for example, Checkout session is complete) instead of directly listening to charge events.

Supported triggers

Workflows support most events as triggers for both Stripe v1 and v2. Unsupported events aren’t available in the Dashboard.

Connected account events

If you use Connect, you can configure a workflow to trigger on events from your connected accounts instead of your platform account. When you create or edit a trigger, select whether the workflow monitors events from your platform account or from connected accounts.

A workflow listens to events from one source — either the platform account or connected accounts, not both. If you need the same workflow logic for both, create separate workflows for each event source.

When a workflow triggers on a connected account event, the connected account ID is available as context throughout the workflow. You can reference it in subsequent actions to operate on that connected account’s resources.

Recurring schedule triggers

You can run workflows automatically on a schedule, such as every hour, every Monday at 9:00 AM, or on the last day of each month. Recurring schedule triggers are useful for recurring batch jobs, reports, and checks. For details, see Recurring schedule triggers.

On-demand triggers

You can trigger workflows on demand from the Dashboard or through the API with custom input data. On-demand triggers are useful when a human needs to initiate a process or when an external system needs to invoke Stripe logic. For details, see On-demand triggers.

Actions

An action is a task that’s performed automatically based on data from the trigger or from previous steps. Every workflow must have at least one action, and most workflows contain several actions in sequence.

Use Wait to pause a run before it continues with the next step.

Some common actions include:

• Update a customer: Modify an existing customer’s details, such as adding custom data using the metadata field for tracking or reporting purposes.
• Retrieve an invoice: Fetch the latest details for a specific invoice including its status. This is typically used to gather data that will be used in a later step, such as updating the invoice or making a decision based on its current state.
• Retrieve a subscription: Fetch the latest details of a customer’s subscription, including their plan and billing cycle. This is typically used to gather subscription data for use in later steps such as updating the subscription or applying condition logic.
• Update a subscription: Modify an active subscription such as changing the plan, updating the billing cycle, or applying a discount.

Workflow steps run in sequence, starting after the trigger event. Each step can access information from the trigger and previous steps through dynamic fields. These fields act as smart placeholders, automatically filling with real-time data as the workflow progresses. This system allows each step to adapt to the data flowing through the workflow, enabling flexible and responsive workflows.

Actions operate on the most recent state of an object at the time the action runs. This means if an object changes between the initial trigger and a subsequent action, the action will affect the latest version of the object. Dynamic references, however, use the state of the object at the time that it was last retrieved.

Supported actions

Workflows supports most API actions for both Stripe v1 and v2. Unsupported actions aren’t available in the Dashboard.

List actions (for example, list customers, list subscriptions, list invoices) are available within loops. A list action returns a collection that the loop iterates over. See Loop over collections for details.

Actions on connected accounts

When a workflow triggers on a connected account event, actions can operate on the connected account’s resources. The workflow sends API calls with the Stripe-Account header set to the connected account that triggered the event.

You can configure each action to operate in one of these contexts:

• Platform account: The action runs against your platform account (default behavior)
• Connected account: The action runs against the connected account that triggered the workflow, using the Stripe-Account header

Not all connected accounts have the same permissions. If a connected account lacks permissions for an action, the action fails at runtime with a permission error.

Actions can operate on both platform and connected account resources. See Connected account events for details on configuring triggers and actions for Connect.

Unique action to Workflows

The following is a unique action to Workflows, meaning it’s only available using the visual builder in the Dashboard and isn’t a part of the public API.

Conditions

Conditions let you add logic to your workflow by defining rules that control whether and how the workflow must proceed. A condition is a check that typically evaluates data from the trigger or earlier steps. Depending on how you use them, conditions can determine whether a workflow runs at all, whether it continues, or which path it must take. The conditions that are available to you depend on which data the workflow plans to reference.

Trigger conditions

Trigger conditions filter which events start your workflow. They’re available only for event triggers. Your workflow only runs if the trigger conditions are true. These are useful for narrowing your workflow to specific use cases, for example only running a workflow for successful payments above a certain amount. Their primary purpose is to determine if the workflow needs to run at all.

Trigger condition configuration in the Dashboard

Here’s how it works:

1. An event happens in your Stripe account.
2. The trigger condition checks if this event meets specific criteria.
3. If the criteria are met, the workflow starts. If not met, nothing happens.

You can create and apply a single condition to a trigger. For example:

You can also create and apply multiple conditions to a trigger. For example:

Conditions help you target your workflows to specific situations, to help refine the precision of your workflows.

Conditions as steps

In addition to trigger conditions, you can add condition steps within your workflow. These condition steps give you control over how the workflow behaves after it starts.

For example, you can add a condition in your workflow as a step to check whether or not specific criteria are met, to determine if the workflow must continue. By adding a condition step, you can evaluate a value and decide whether to proceed. If the condition is true, the workflow advances to the next step; but if false, the workflow stops and is marked as successful. Use this approach to verify outcomes after completing actions.

Branch conditions

Another example of a condition step is using a condition as a branch. This allows you to introduce decision points within a workflow, letting it diverge into multiple paths based on specified criteria. You can build multiple paths from a condition step, allowing the workflow to follow different paths that take different actions based on different criteria. Use this approach for handling multiple scenarios, such as sending different emails to different account teams based upon the customer’s country or purchase amount.

Example of a condition that creates two branches:

You can also create more than two branches by adding more conditions. This allows your workflow to handle multiple scenarios from a single decision point.

Example of conditions that create 3 branches:

Each condition is evaluated in order from left to right in the visual builder. The workflow follows the first matching path and skips the others. Trigger conditions determine whether the workflow needs to run at all. Condition steps control what happens after the workflow starts, either by deciding whether to continue or by branching into different paths.

In many cases, the same condition logic might be used at the trigger or step level. Where you apply a condition depends on what you want to control, whether the workflow must start, whether it must continue after starting, or which path it must take during its run.

Loops

Loops let you iterate over a collection of Stripe objects and run a sequence of actions for each item. For example, you can loop over all subscriptions for a customer and update metadata on each one.

You add a loop by selecting a for-each step in the workflow builder. The loop takes a collection as input (typically the result of a list API action) and executes the actions inside the loop body once per item.

For details on configuring loops, supported collections, failure handling, and limits, see Loop over collections.

Wait

Use a Wait step to pause a workflow run for a set duration or until a specific date and time. The run continues with the next step shortly after the wait ends. Waits work the same way in sandboxes.

In the workflow builder, select Add wait. In the configuration drawer, choose a Wait type:

• Duration: Under Wait for, enter a whole number and choose Minutes, Hours, Days, or Weeks. The duration starts when the run reaches the step and must be at least 5 minutes and at most 90 days.
• Target time: Under Wait until, choose a date and time in the future, no more than 90 days ahead. Select a Timezone, which defaults to your account’s time zone.

The combined configured wait time across all Wait steps in a workflow can’t be more than 365 days. A wait can’t be the last step of a workflow. You can place a wait at the end of a loop body to pace each iteration.

While a run is paused, the Wait step shows Waiting in the run details, along with the elapsed time. Deactivating a workflow doesn’t stop runs that are already waiting. They continue when the wait ends. To stop a waiting run, open the run in the Dashboard, select Cancel run, and confirm in the Cancel run? dialog. The run stops immediately, and any incomplete steps don’t run.

Retrieve updated data

Objects retrieved before a wait might change before the run resumes. In the wait’s configuration drawer, use Retrieve updated data to select data to refresh. This adds retrieval steps after the wait. Use the results of those retrieval steps in later steps to work with current values.

For example, to notify a team member about an invoice that remains unpaid after 3 days:

1. Use the Invoice is finalized trigger (invoice.finalized).
2. Add a Wait step with a Duration of 3 Days.
3. Under Retrieve updated data, select the invoice to add a retrieval step after the wait.
4. Add a condition that checks whether the retrieved invoice’s status is open, and add Email team member on the matching path.

Custom actions

Custom actions are user-defined actions that appear in the workflow builder alongside built-in Stripe actions. App developers build custom actions using the extend.workflows.custom_action extension interface.

Custom actions can be implemented as TypeScript scripts that run in Stripe’s sandbox, or as remote functions that call your own HTTP endpoints. They support dynamic configuration like dropdowns, conditional fields, and validation.

For details on building and deploying custom actions, see Create custom actions.