# Loop over collections

Iterate over lists of Stripe objects and apply actions to each item.

Loops let you apply the same actions to each item in a collection of Stripe objects. For example, you can loop over all subscriptions for a customer, all open invoices, or all charges for a payment intent, and run actions on each one.

## What loops do

A loop is a for-each construct in the workflow builder. It takes a collection as input and executes a sequence of actions once per item. Items are processed one at a time, in order. Loops pair with list actions to process data at scale. Without loops, each action in a workflow operates on a single object. With loops, a workflow can retrieve a collection of objects and act on each one individually. You can use any list action that Workflows supports, such as List customers, List subscriptions, List invoices, List charges, or List payment intents. Loops can be nested: you can place a loop inside another loop to handle hierarchical data (for example, loop over customers, then loop over each customer’s subscriptions).

## How to add a loop

1. In the workflow builder, add a list action (for example, **List subscriptions** or **List customers**) to retrieve the collection you want to iterate over.
1. Add an action after the list action (for example, **Update invoice** after **List invoices**). When you configure the action and dynamically reference a field from the list results (such as the invoice ID), the workflow builder automatically introduces a for-each loop. Each iteration receives one item from the collection.
1. Add more actions inside the loop body as needed. These actions run once per item, with access to the current item’s fields.
1. Add conditions inside the loop to filter which items receive actions (optional).

## Pagination

The loop processes items in the order the list API returns them. When a list action returns more results than fit in a single API page, the loop handles pagination automatically. Results are fetched page by page during execution: page 1 items are processed first, then page 2, and so on. The loop doesn’t pre-fetch all pages upfront. Pagination tokens ensure consistent ordering across pages, but any items created after the list action begins execution aren’t included in the results.

Smaller collections run faster and use fewer actions. Configure the list action’s filters to narrow the collection before looping.

## Failure handling

When an action inside a loop fails for a specific item, the loop stops immediately (fail-fast). No further items are processed. In run details, you can see which items succeeded before the failure.

Fail-fast is appropriate when:

- The items are related, and a failure on one makes processing the rest pointless
- You want to fix the issue before continuing
- Data consistency across all items matters

## Planning your loop size

Each action inside a loop body counts once per iteration. For example, a loop body with 3 actions processing 200 items runs 600 total actions. Actions outside the loop (such as the list action, conditions, or other actions) also count toward your workflow’s total. Larger loops take longer to run and cost more, so configure the list action’s filters to keep collections focused.

## Observability

Loop execution appears in **Run details** with per-iteration tracking. Each iteration shows its individual result (succeeded, failed, or skipped). If a loop fails, run details show which iteration failed and what error occurred. Items that succeeded before the failure are marked as completed.

## Example: Tag all active subscriptions for a customer

This example walks through building a workflow that adds a metadata tag to all active subscriptions for a specific customer.

### Workflow structure

```
Manual trigger
  → List subscriptions (customer = customer_id, status = active)
  → For each subscription:
    → Update subscription: add metadata entry
```

Set up the workflow

1. **Create the workflow.** Navigate to **Workflows** and click **Create workflow**. Name it “Tag customer subscriptions.”

1. **Configure the trigger.** Select **Manual trigger** and define three input parameters:

   - `customer_id` (string) — the customer whose subscriptions to tag
   - `tag_key` (string) — the metadata key to add
   - `tag_value` (string) — the metadata value to set

1. **Add a list action.** Add **List subscriptions**. Set the `customer` parameter to the `customer_id` from the trigger input.

1. **Add a condition.** Add a condition that checks whether the subscription status equals `active`. This filters the list so only active subscriptions proceed to the next step.

1. **Add an action inside the loop.** Add **Update subscription**. Set the subscription ID by dynamically referencing the current item’s ID from the list results — this automatically creates a for-each loop. Add a metadata entry with the key from `tag_key` and the value from `tag_value` from your trigger.

1. **Publish** the workflow.

1. **Run the workflow.** Click **Run** and provide inputs, such as:

   ```json
   {
     "customer_id": "cus_ABC123",
     "tag_key": "promo_eligible",
     "tag_value": "2026_spring"
   }
   ```

1. **Check results.** Open **Run history** to verify. Each subscription update appears as a separate iteration in the loop details.

## See also

- [Workflows](https://docs.stripe.com/workflows/define-workflows.md)
- [Set up workflows](https://docs.stripe.com/workflows/set-up.md)
- [Use cases](https://docs.stripe.com/workflows/use-cases.md)
- [Custom actions](https://docs.stripe.com/workflows/custom-actions.md)
- [Trigger workflows programmatically](https://docs.stripe.com/workflows/programmatic-triggers.md)