> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Automate business processes with workflow pipelines of filters, delays, and actions

export const viewAccessDefinition = "Read-only access without ability to make changes.";

export const editAccessDefinition = "Update and read data, but cannot create or delete.";

export const manageAccessDefinition = "Create, update, read, and delete data.";

export const permissionsDefinition = "The actions you are authorized to perform.";

export const visibilityDefinition = "Which features, sections, or data tables are visible to you.";

export const userRoleDefinition = "What a user can see and do. Each user has one built-in system role — Owner, Admin, Manager, or Member — and can also be assigned any number of custom roles you create with specific permissions. Effective access is the combination of all their roles.";

Workflows let you automate repetitive business processes by chaining filters, delays, and actions into a pipeline. A workflow runs against a payload — such as an Order — and executes its steps in order.

<Info>
  This view can look different dependent on your user role. <br />See [Visibility & Permissions](#visibility-and-permissions) for details.
</Info>

## Primary Purpose

Workflows remove manual work by reacting to events in your system and performing actions on your behalf.

<AccordionGroup>
  <Accordion title="Create Automation Rules">
    Build workflows that fire when specific events occur — an order ends, an item is returned, or a status changes.
  </Accordion>

  <Accordion title="Filter and Delay">
    Add filters to narrow which events qualify and delays to control timing. For example, wait two hours after an order ends before sending a feedback email.
  </Accordion>

  <Accordion title="Configure Actions">
    Choose what happens at the end of the pipeline: send an email with a custom subject and body, or send an HTTP request to an external system. See [Action Types](#action-types) for details.
  </Accordion>

  <Accordion title="Monitor Execution">
    Review workflow run history, check success and failure counts, and debug issues when a step does not complete.
  </Accordion>
</AccordionGroup>

## Workflow Pipeline

A workflow is a pipeline of three step types that execute in order:

| Step       | Purpose                         | Example                       |
| ---------- | ------------------------------- | ----------------------------- |
| **Filter** | Narrows which payloads qualify  | Only orders over €100         |
| **Delay**  | Pauses execution for a set time | Wait 2 hours                  |
| **Action** | The operation to perform        | Send "Feedback Request" email |

Filters and delays are optional. A minimal workflow needs only an action.

<Note>
  Workflows are currently started **through the API**: a job is created for a workflow with a payload (for example an Order object), and the pipeline runs against that payload. The admin has a Workflows entry, but it shows a placeholder marked "Coming soon" — event triggers and a visual builder are not available yet, and there is no committed release date for them.
</Note>

## Example

A workflow that sends a feedback request email two hours after it is started with an order payload:

<CodeGroup>
  ```json Workflow Definition theme={null}
  {
    "name": "Post-Order Feedback",
    "steps": [
      {
        "type": "delay",
        "duration": "2h"
      },
      {
        "type": "action",
        "action": "send_email",
        "template": "feedback_request"
      }
    ]
  }
  ```
</CodeGroup>

## Failure Handling

### Retries

When a workflow job fails on a server error (5xx) or a network failure, the system retries it several times before marking the job permanently failed. Error responses in the 4xx range are treated as permanent and are not retried.

### Auto-disable

If the 3 most recent jobs for a workflow all fail, the workflow is automatically disabled. A disabled workflow stops processing new jobs until it is re-enabled.

Fix the root cause of the failures first, then contact support to re-enable the workflow — re-enabling is not currently available in the admin or the public API.

<Note>Workflow retries are separate from [webhook delivery retries](/docs/concepts/integrations/webhooks). The two mechanisms operate independently.</Note>

## HTTP Request Actions

HTTP request actions send requests to external URLs as a workflow step. They support `GET`, `POST`, `PUT`, and `DELETE` methods.

### Headers

Every request includes two system-managed headers:

| Header            | Value              |
| ----------------- | ------------------ |
| `Content-Type`    | `application/json` |
| `X-Origin-System` | `TwiceCommerce`    |

Custom headers are not supported. Any headers configured on the action are removed before the request is sent.

### Error handling

By default, an HTTP request action that receives a 5xx error response or a network failure fails the job and enters the retry cycle described above; a 4xx response fails the job permanently without retries. Enable **Continue on error** to pass the error response to the next workflow step instead of failing.

## Related Concepts

<AccordionGroup>
  <Accordion title="Filters">
    Filters evaluate conditions against the job payload and stop the pipeline if the conditions are not met.
  </Accordion>

  <Accordion title="Delays">
    Delays pause execution for a configurable duration before continuing to the next step.
  </Accordion>

  <Accordion title="Actions">
    Actions are the operations a workflow performs. Available actions include sending emails from templates and making HTTP requests to external URLs. See [HTTP Request Actions](#http-request-actions) for details on headers and error handling.
  </Accordion>
</AccordionGroup>

## Action Types

### Send Email

Sends an email with a custom subject and body. Both fields support [template variables](#template-variables). HTML tags in the body are stripped for security. The email is sent from TWICE Commerce on behalf of your account.

### HTTP Request

Sends an HTTP request to an external URL. Use this to notify third-party systems, trigger external automations, or push order data to your own backend.

**Supported methods:** `GET`, `POST`, `PUT`, `DELETE`. For `GET` and `DELETE` requests, no body is sent.

Every outgoing request includes two auto-injected headers:

| Header            | Value              |
| ----------------- | ------------------ |
| `Content-Type`    | `application/json` |
| `X-Origin-System` | `TwiceCommerce`    |

Custom headers are not configurable.

Only JSON request bodies are accepted — the body template must be valid JSON. Non-JSON content types are not supported.

<CodeGroup>
  ```json Example body template theme={null}
  {
    "event": "order_created",
    "order_id": "{{ $.id }}",
    "status": "{{ $.status }}",
    "channel": "{{ $.channel }}"
  }
  ```
</CodeGroup>

### Template Variables

Both action types support template variables in their text fields — email subject and body, request URL query parameters, and request body. Use `{{ $.path }}` syntax, where `$` represents the job payload.

When a workflow is started with an Order payload, templates resolve against that Order object. Nested paths use dot notation. Array elements use bracket notation (`[0]`, `[1]`).

| Template                    | Resolves to                |
| --------------------------- | -------------------------- |
| `{{ $.id }}`                | The order ID               |
| `{{ $.status }}`            | The order status           |
| `{{ $.number }}`            | The order number           |
| `{{ $.lineItems[0].name }}` | The first line item's name |

Template values in HTTP requests are automatically encoded based on where they appear:

| Context          | Encoding                                                   |
| ---------------- | ---------------------------------------------------------- |
| Request body     | JSON-escaped (quotes, backslashes, and control characters) |
| Query parameters | URL-encoded                                                |

## Visibility and Permissions

Workflow management is currently API-only. Workflow endpoints are available to any authenticated user of your account. Workflows have no role-based restrictions of their own.