WorkflowsPublic preview

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 have the ability to activate, deactivate, or delete workflows. After you deactivate a workflow, Stripe considers it as inactive and it no longer responds to triggers. You can reactivate an inactive workflow anytime you want. You can maintain up to 6 active workflows at a time and have a combined total of 20 workflows, which includes both active and inactive ones.

If you have 20 workflows, you can’t create another workflow. If you have 6 active workflows, and want to activate another one, you must first deactivate an already active workflow.

Triggers

Workflows are started by Stripe API events. Each workflow has one trigger, and it’s always the first step of a workflow. The trigger provides data about the event. 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.

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 whether a charge succeeds or fails, the following triggers can apply to you. Note that 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.

Using Connect with triggers

Stripe Connect platforms and marketplaces can trigger workflows using events from the platform account, but not from connected accounts. This means you can trigger workflows for something in your platform account, such as when a payment succeeds, but you can’t trigger workflows directly from events that occur in your connected accounts.

Actions

An action is task that is 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.

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. All Stripe list actions are currently unsupported as actions (for example, list actions for disputes).

Using Connect with actions

Stripe Connect platforms and marketplaces can use actions in workflows through the platform account, but not through connected accounts. This means your workflow can perform actions such as refunding a payment or updating a customer in your platform account, but it can’t directly perform actions in your connected accounts

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. 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 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.

Additional built-in features

• Recursion detection: To prevent the creation of unintentional infinite loops or runaway workflows, Workflows automatically identifies and stops such recursions. For example, consider a workflow triggered by a customer event, that also includes an action to update the customer’s information. Performing this action generates another customer updated event, which could re-trigger the same workflow, leading to a potential infinite loop. To protect against this, Workflows allows recursion to occur only once; however, if it happens more than once the workflow ends with an error.

• Automatic retries: To improve reliability, Workflows automatically retries actions that encounter retriable errors. This means that if an action fails due to a transient issue, the workflow attempts to run it again without requiring any manual intervention from you. This ensures temporary errors don’t cause workflow failures, promoting smooth and consistent workflow runs.

• Idempotency: Idempotency ensures that actions are only run once, even if the same request is submitted multiple times. Workflows automatically handles duplicate requests, preventing unintended repeated actions. This safeguard helps ensure consistency when network issues or errors might lead to retrying requests.

• Observability: Observability helps you monitor, troubleshoot, and resolve issues within your workflow quickly. Workflows provides the following to help with observability:

  • Run status: Each workflow can have one of three statuses, “running”, “succeeded”, or “failed”. In the case of a failure, a detailed error message is provided to help you quickly diagnose and resolve the issue.
  • Run details: You can inspect individual workflow runs to view the exact run path, including which steps were executed, the parameters used, and any errors encountered. This visibility allows you to quickly pinpoint which step in your workflow caused an error as well as understand the path an execution took.