# Overview

What JsWorkflows is and how it works.

JsWorkflows is a Shopify-first automation platform for merchants and teams that need more control over store operations.

It is built for workflows that solve real operational problems across catalog, inventory, orders, fulfillment, customers, reporting, exception handling, and external system coordination.

JsWorkflows is not a visual drag-and-drop rule builder. It combines production-ready templates with editable JavaScript workflows, so you can start with a working solution and still adapt the logic to your store as requirements grow.

## When JsWorkflows is a good fit

JsWorkflows is a strong fit when your store needs workflows that are:

- focused on store operations and custom business logic, not just generic notification or marketing flows
- specific to your business rules
- too complex for simple rule builders
- connected to Shopify data and external systems
- dependent on review, approval, or other human decision points
- easier to maintain as code than as a large visual flow

Common examples include:

- reacting to Shopify events with store-specific business logic
- scheduled reporting, audits, and operational checks
- catalog and merchandising workflows
- inventory, order, and fulfillment exception handling
- customer, returns, and risk-related workflows
- imports, syncs, and reconciliation jobs
- sending data or actions to connected external services

If you only want simple no-code recipes with a visual canvas, JsWorkflows may not be the best fit. It is built for workflows where flexibility, control, and operational depth matter more than drag-and-drop simplicity.

## Templates and custom workflows

JsWorkflows supports both templates and fully custom workflows across a wide range of Shopify operational use cases.

Templates are production-ready starting points for common operational tasks. They can include:

- configuration fields
- setup instructions
- starter workflow code
- tested patterns for a specific use case

After you save a template workflow, you can still inspect and edit the generated code.

This is one of the main strengths of the platform:

- start from a template when you want speed
- edit the workflow when your store needs something more specific

The template library is intended to cover practical store operations workflows, not just simple demos or narrow connector examples.

You can also create a workflow entirely from scratch if you already know the logic you want to build.

## How workflows run

Under the hood, workflows are written as code. Each workflow is a JavaScript class. You define one or more step methods on the class, while JsWorkflows handles triggering, scheduling, execution, run tracking, and connections to external services.

```js
export class Workflow {
  async start(data, headers, api) {
    // your code runs here
  }

  async nextStep(data, headers, api) {
    // scheduled steps run here
  }
}
```

Every step method receives three arguments:

| Argument | Description |
| --- | --- |
| `data` | The trigger payload, such as an order, customer, HTTP body, or scheduled run metadata |
| `headers` | The HTTP headers from the trigger request |
| `api` | The JsWorkflows API for fetch, scheduling, state, OAuth, secrets, logging, and platform helpers |

## Core concepts

| Concept | Description |
| --- | --- |
| **Workflow** | A JavaScript class that defines your automation logic |
| **Step** | A method on the workflow class |
| **Trigger** | What starts a run, such as a Shopify webhook, HTTP request, inbound email, schedule, or manual test |
| **Run** | One full execution of a workflow from trigger to completion |
| **Template** | A workflow starter with configuration and prebuilt code |
| **Variable / Secret** | Per-workflow settings and secrets used by your code |
| **OAuth handle** | The name of a connected external service used with `api.getOAuthToken()` |
| **Credit** | The billing unit, with one credit used per step execution |

## Execution model

- The `start` method is always the entry point.
- To continue the workflow later, call `api.scheduleNextStep()`.
- Multiple `scheduleNextStep()` calls in one step create parallel branches.
- A run is only marked complete when all scheduled branches have finished.
- Steps that use `api.waitForEvent()` pause the run until an external signal resumes it.

This execution model is especially useful for:

- scheduled operations
- review and approval workflows
- delayed follow-up actions
- fan-out workflows that process many records safely

It is especially useful for operational workflows that need retries, batching, delayed follow-up, fan-out processing, or coordination across multiple steps.

It also supports human-in-the-loop workflows, where a run pauses until someone reviews a case, approves a change, or sends the next signal that lets the workflow continue.

## Workflow lifecycle hooks

Two optional methods can be defined on the Workflow class:

```js
export class Workflow {
  async start(data, headers, api) { ... }

  async onWorkflowComplete(api) {
    // Called when the entire run finishes successfully
  }

  async onWorkflowError(err, api) {
    // Called when a step throws an uncaught error
  }
}
```

Both hooks receive a restricted `api`: `getOAuthToken`, `google`, `log`, `dedupe`, and `runStore` are available. `scheduleNextStep`, `waitForEvent`, and `csv` are not.