@blackswampai/n8n-nodes-medusa

An n8n community integration for the Medusa v2 Admin API, with first-class self-hosted support.

This is an independent Black Swamp AI community integration. It is not affiliated with, endorsed by, sponsored by, or maintained by Medusa. The Medusa name and logo belong to their respective owner(s) and are used only to identify compatibility.

Medusa is an open source, self-hostable commerce platform built as a modular set of commerce primitives — products, orders, inventory, fulfillment, pricing and promotions — exposed through an API-first Admin API. This node targets that Admin API, so it works against any Medusa installation you control, self-hosted or otherwise.

n8n is a fair-code licensed workflow automation platform.

Installation · Operations · Credentials · Compatibility · Known limitations · Troubleshooting · Resources · Black Swamp AI

Installation

On the n8n canvas, open the nodes panel, search for Medusa, select it under More from the community, and choose Install. On self-hosted n8n, administrators may alternatively install the exact package name @blackswampai/n8n-nodes-medusa through Community Nodes settings.

Operations

Product

| Operation | Notes | | --------- | ----------------------------------------------------------------------------------------------------- | | Create | Requires a title and at least one priced variant | | Get | By ID, with optional field selection and relation expansion | | Get Many | Filter by search, status, handle, category, collection, and created/updated date; Return All or Limit | | Update | Any subset of title, subtitle, description, handle, status, discountable, external ID and metadata | | Delete | By ID |

Medusa requires every product to declare at least one option axis, and every variant to carry matching option values. Rather than make that mandatory, the node derives a single axis from your variant titles, so creating a product needs only a title, a variant name and a price. Products that genuinely vary along several dimensions — size and colour — can supply the axes explicitly through the Product Options and Variant Options fields.

Product Variant

| Operation | Notes | | --------- | ---------------------------------------------------------------------------- | | Create | On an existing product; requires a title and at least one price | | Get | By product ID and variant ID | | Get Many | Variants of one product, or across every product when no product ID is given | | Update | Title, SKU, barcodes, inventory tracking, metadata, and the full price list | | Delete | By product ID and variant ID |

Variants are always addressed through their product, because that is how Medusa's API is shaped. The cross-product route used by Get Many is the one exception, and it cannot filter by product — supply a Product ID and the node switches to that product's own route instead.

Medusa will not invent option values. A variant can only use option values already declared on its product, so add the value to the product first if it is new.

Product Category

| Operation | Notes | | ------------ | ---------------------------------------------------------------------- | | Create | Requires a name | | Get | By ID | | Get Many | Filter by search, handle, parent category, active and internal flags | | Update | Name, description, handle, ranking, parent, visibility flags, metadata | | Delete | By ID | | Add Products | Add and remove products in one call |

Medusa creates categories inactive. Set Is Active for the category to appear in a storefront.

Product Collection

| Operation | Notes | | ------------ | ----------------------------------- | | Create | Requires a title | | Get | By ID | | Get Many | Filter by search, title, handle | | Update | Title, handle, metadata | | Delete | By ID | | Add Products | Add and remove products in one call |

Customer

| Operation | Notes | | ---------- | -------------------------------------------------------------------------------- | | Create | Requires an email | | Get | By ID | | Get Many | Filter by search, exact email, company, account status, and created/updated date | | Update | Email, name, company, phone, metadata | | Delete | By ID | | Set Groups | Add and remove group membership in one call |

Medusa will accept a customer with no fields at all, creating a record that cannot be contacted or matched against an existing one. The node requires an email to prevent that.

Customer Group

| Operation | Notes | | ------------- | ------------------------------------------ | | Create | Requires a name | | Get | By ID | | Get Many | Filter by search, exact name, created date | | Update | Name, metadata | | Delete | By ID | | Set Customers | Add and remove members in one call |

Membership can be changed from either end — Customer → Set Groups, or Customer Group → Set Customers — whichever fits the workflow better.

Inventory Item

| Operation | Notes | | --------------------- | ------------------------------------------------------------------- | | Create | Requires a SKU | | Get | By ID | | Get Many | Filter by search, exact SKU, created/updated date | | Update | SKU, title, dimensions, customs fields, metadata | | Delete | By ID | | Get Location Levels | Stock held for this item across locations | | Set Location Level | Sets stock at one location, creating the level if it does not exist | | Delete Location Level | Stops tracking this item at a location |

Set Location Level is the operation a warehouse feed wants. Medusa splits this across two routes — one that creates a level and one that updates it — and creating a level that already exists fails. A sync does not know which case it is in, so this operation checks and picks. That costs one extra request per call.

Medusa refuses to delete a level while stock remains at that location. Set the stocked quantity to 0 first.

Stock Location

| Operation | Notes | | ------------------ | ------------------------------------------------ | | Create | Requires a name; accepts a physical address | | Get | By ID | | Get Many | Filter by search, exact name | | Update | Name, address, metadata | | Delete | By ID | | Set Sales Channels | Add and remove the channels this location serves |

Order

| Operation | Notes | | --------------------------- | ------------------------------------------------------------------------------------------ | | Get | By ID | | Get Many | Filter by search, status, payment status, fulfillment status, region, created/updated date | | Get Line Items | The order's line items | | Get Changes | The order's change history | | Update | Email and metadata only | | Complete · Cancel · Archive | State transitions |

Medusa has no create and no delete for orders. Orders come from checkout, and are cancelled or archived rather than removed. Draft orders, which is how an order is authored administratively, are a separate 21-endpoint flow planned for a later release.

Status is not an editable field — Medusa rejects it in an update body — so each transition is its own operation, and each has preconditions Medusa enforces:

• A completed order cannot be cancelled. Use the returns process instead.
• A cancelled order cannot be completed.
• An order with active fulfillments cannot be cancelled until those are cancelled first.
• Either terminal state can be archived.

Some fields, including email, are not returned unless you ask for them by name in Fields. This is easy to mistake for the value being empty.

Fulfillment

| Operation | Notes | | ----------------- | ------------------------------------- | | Create | Fulfil line items on an order | | Get Many | The fulfillments of an order | | Create Shipment | Record that a fulfillment has shipped | | Mark as Delivered | Record delivery | | Cancel | Only while unshipped |

Fulfillments are always addressed through their order. Medusa has no read endpoint for fulfillments at all, so Get Many reads them by expanding the order.

A shipped fulfillment cannot be cancelled.

Region

| Operation | Notes | | -------------------------------- | --------------------------------- | | Create | Requires a name and currency code | | Get · Get Many · Update · Delete | |

A country belongs to exactly one region. Assigning one that another region already covers is rejected — the most common surprise when scripting region setup.

Sales Channel

| Operation | Notes | | -------------------------------- | ----------------------------------- | | Create | Requires a name | | Get · Get Many · Update · Delete | | | Add Products | Add and remove products in one call |

Channel membership is readable from the product side (Product → Get with fields=id,*sales_channels), not from the channel.

Price List

| Operation | Notes | | -------------------------------- | -------------------------------------- | | Create | Requires a title and a description | | Get · Get Many · Update · Delete | | | Get Prices | Prices in the list | | Add Prices | Add variant prices | | Add Products | Add and remove products in one call |

Promotion

| Operation | Notes | | -------------------------------- | ---------------------------------------------------------- | | Create | Code, discount type, value, what it applies to, allocation | | Get · Get Many · Update · Delete | |

Medusa requires a max quantity when the allocation is Each, and a currency for a fixed-amount discount. The node collects both and refuses early rather than letting the request fail. Changing the discount itself after creation is not supported — recreate the promotion instead.

Not in this release

Returns, exchanges, claims, order edits and draft orders are multi-step workflows rather than CRUD, and each needs its own design. Promotion rule builders, campaigns, reservations, batch operations and product import/export are also deferred.

Medusa's Store API — carts, checkout and storefront browsing — is out of scope.

Credentials

You need a Medusa secret API key. Publishable API keys are scoped to sales channels for storefront use and will not authenticate against the Admin API.

1. Sign in to your Medusa admin dashboard as an administrator.
2. Go to Settings → Secret API Keys and create a key.
3. Copy the token when it is shown. Medusa displays it once.

The credential takes two fields:

| Field | Value | | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Base URL | The root URL of your Medusa server, without the /admin path — for example https://commerce.example.com or http://localhost:9000 | | API Token | The secret API key token |

Medusa's Admin API authenticates secret keys using the HTTP Basic scheme. The node sets that header for you; you only supply the token.

Compatibility

• Requires n8n with n8nNodesApiVersion 1.
• Requires Node.js 22.22.0 or later.
• Developed and tested against Medusa 2.x. Medusa v1 uses a different Admin API and is not supported.

Known limitations

Deleting a record that does not exist reports success. Medusa answers every delete with { "deleted": true } and HTTP 200, whether or not anything was there to remove:

DELETE /admin/products/does_not_exist  →  200  { "id": "does_not_exist", "deleted": true }

This is Medusa's behaviour, not the node's, and it applies to every resource. A workflow that branches on deleted is therefore confirming that the record is gone, not that this node removed it. Read the record first if you need to tell those two cases apart.

Medusa has no generic outgoing webhook registration. Its events are emitted through the Event Module to subscribers that run inside the Medusa application itself, so there is no Admin API route an external system can call to subscribe. This node therefore has no trigger — it is an action node. Event-driven support depends on a companion Medusa plugin that forwards events over HTTP, which is planned separately.

Troubleshooting

• Use the Medusa server root as Base URL; do not append /admin.
• Use a secret API key, not a publishable storefront key.
• Some Admin API fields are omitted unless requested through Fields; an absent field is not necessarily empty.
• For delete workflows that must distinguish “removed now” from “already absent,” Get the record first because Medusa reports both cases as deleted.

Resources

• n8n community nodes documentation
• Medusa Admin API reference
• Medusa documentation
• API and observed-behavior matrix
• Testing and qualification
• Branding provenance
• Version history

Release provenance

Releases are published only from immutable version tags through GitHub Actions with npm provenance. The official n8n scanner checks source and built artifacts before publication and the published registry package afterward.

License

MIT