Flow builder plugin
Shopify-Flow-style visual workflow automation for Medusa v2 — draggable node editor, .flow file import/export, extensible task registry.
medusa-flow-builder-plugin
Shopify-Flow-style visual workflow automation for Medusa v2.
- Draggable node editor in the admin dashboard — trigger → conditions → wait → actions.
- file import and export that interchanges with Shopify Flow. Task IDs translate both directions.
- Extensible task registry — register your own triggers, conditions, and actions from your app with .
- Durable WAIT — resumptions survive restarts via a persisted pending-resumption table + 1-minute cron sweeper.
- Built-in task catalog — 15 triggers, 2 control nodes (wait, condition), 13 actions covering orders, customers, products, webhooks, Slack, Customer.io, and log output.
Status: alpha. API may change. Not yet published to npm — for now, consume via Medusa's local-package workflow (yalc-based).
Install
Once published to npm
Until then — local install via Medusa's plugin CLI
In the plugin repo:
In the consumer Medusa app:
Register in your app's :
Run the migration so the plugin's tables are created:
yarn medusa db:migrateOpen the admin dashboard → sidebar Extensions → Flow Builder.
New devs: see for an end-to-end setup walkthrough that assumes zero Medusa experience.
Built-in tasks
| Kind | Task ID | Description |
|---|---|---|
| Trigger | Order placed | |
| Trigger | Order paid | |
| Trigger | Order fulfilled | |
| Trigger | Order canceled | |
| Trigger | Order refunded | |
| Trigger | Order updated | |
| Trigger | Customer created | |
| Trigger | Customer updated | |
| Trigger | Product created | |
| Trigger | Product updated | |
| Trigger | Product deleted | |
| Trigger | Cart updated | |
| Trigger | Fulfillment created | |
| Trigger | Inventory level changed | |
| Trigger | Public inbound webhook () | |
| Control | Pause N seconds/minutes/hours/days before continuing | |
| Control | Route through / output ports | |
| Action | Append tags to order metadata | |
| Action | Remove tags from order metadata | |
| Action | Set a namespaced metafield on an order | |
| Action | Merge keys into | |
| Action | Cancel an order | |
| Action | Append customer tags | |
| Action | Remove customer tags | |
| Action | Set a namespaced metafield on a customer | |
| Action | Append product tags | |
| Action | POST JSON to a URL | |
| Action | POST a message to a Slack incoming webhook | |
| Action | Send a Customer.io transactional message (requires installed) | |
| Action | Log a templated line to the server logger |
All action config fields support template interpolation against the triggering event's payload.
Registering your own tasks
Create a file in your app that runs at boot time — a subscriber, a loader, or :
The task appears in the admin palette immediately. Re-registering the same overrides the previous definition, including built-ins.
For custom triggers bound to events Medusa doesn't fire natively, register the trigger AND write a subscriber that forwards the event:
The plugin already ships umbrella subscribers for the built-in triggers listed above.
file import / export
The list page has an Import .flow button that accepts Shopify Flow exports. Shopify s are translated to their Medusa equivalents on import (see ). Unmapped tasks are preserved as-is with an "unsupported" note — flows still open in the editor; unmapped steps are skipped at runtime.
Each row in the list page has an Export .flow button. Exports include a matching SHA-256 prefix of the JSON body. Task IDs reverse-translate to Shopify identifiers where a mapping exists, so the file drops back into Shopify Flow cleanly.
Durable WAIT
When a run hits a step, it writes a row to (, , , , ) and stops that branch. A cron job runs every minute, sweeps due resumptions, and re-enters the runner at the step downstream of the wait. Runs survive restarts.
Units supported: , , , . Resolution is 1 minute; sub-minute waits will fire on the next cron tick.
Local development
Medusa's plugin workflow is yalc-based. Each consuming app gets a copy of the built plugin under its own directory, with a reference in — no npm registry needed during development.
For the rapid edit-loop while developing the plugin:
If you don't want the watcher, do it manually after each change:
Heads up: from errors with . As a workaround, run followed by raw — same end result. The bug appears fixed in ; we'll switch back to the official command once the consumer app upgrades.
Heads up #2: only copies plugin files into the consumer's directory — it does not re-resolve transitive . If you change the plugin's field, the consumer needs to re-fetch them:
Publishing to npm (when ready)
The script re-runs the build for you, so consumers always get the compiled output. Only the contents of the whitelist (, , , , ) end up in the published tarball — source is not shipped.
Testing
yarn test:unitThe suite covers: condition evaluation, template interpolation, WAIT duration parsing, import/export round-trip, the Shopify↔Medusa task translation, and the extensibility hook.
License
MIT © Rx-Ventures

