Integration Module 2.0 for Medusa is outRead the announcement
Flow builder plugin logo

Flow builder plugin

Shopify-Flow-style visual workflow automation for Medusa v2 — draggable node editor, .flow file import/export, extensible task registry.

npm install @rx-ventures/medusa-flow-builder-plugin
Category
Built by
Version
1.0.0
Last updated
6 months ago
Monthly downloads
Loading downloads

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:migrate

Open 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

KindTask IDDescription
TriggerOrder placed
TriggerOrder paid
TriggerOrder fulfilled
TriggerOrder canceled
TriggerOrder refunded
TriggerOrder updated
TriggerCustomer created
TriggerCustomer updated
TriggerProduct created
TriggerProduct updated
TriggerProduct deleted
TriggerCart updated
TriggerFulfillment created
TriggerInventory level changed
TriggerPublic inbound webhook ()
ControlPause N seconds/minutes/hours/days before continuing
ControlRoute through / output ports
ActionAppend tags to order metadata
ActionRemove tags from order metadata
ActionSet a namespaced metafield on an order
ActionMerge keys into
ActionCancel an order
ActionAppend customer tags
ActionRemove customer tags
ActionSet a namespaced metafield on a customer
ActionAppend product tags
ActionPOST JSON to a URL
ActionPOST a message to a Slack incoming webhook
ActionSend a Customer.io transactional message (requires installed)
ActionLog 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:unit

The 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