Brand

@mgtalabs/medusa-brand

A commercial-grade Brand Management plugin for Medusa v2 — full CRUD with soft delete/restore, a one-brand-to-many-products relationship built on Medusa's official Module Link system, Admin and Store REST APIs, an Admin dashboard UI, and events other plugins can subscribe to.

Compatibility

Built and tested against Medusa 2.18.0. Requires @medusajs/medusa, @medusajs/framework, and the other packages listed under peerDependencies to already be present in the consuming application (they are, for any standard Medusa v2 project).

Features

• Brand CRUD: create, update, soft delete + restore, permanent delete
• One brand → many products, via a Module Link (not a direct foreign key — see docs/architecture.md in the workspace for why)
• Assign a brand at product-creation time through the normal Admin product form (additional_data.brand_id), or manage assignment after the fact from either side — the product's Admin page (see below), the brand's own detail page, or via the Brand's product endpoints directly
• Storage-provider-agnostic logo/banner fields (plain URL + file id — works with local, S3, MinIO, Cloudinary, or any configured Medusa File Module provider)
• Bulk delete/restore
• Search (q param), status/featured filtering, pagination and sorting on all list endpoints
• Admin dashboard: a Brands list, a Brand detail page (edit brand fields, plus a searchable/paginated multi-select product picker to assign, add, or remove products in bulk), a "Products" section in the Create Brand form to assign products at creation time, and a Product-detail widget for assigning, changing, or removing that product's brand from the product's own page
• Configurable via plugin options: enableSEO, enableFeaturedBrands, logoRequired
• Events (brand.created, .updated, .deleted, .restored) and workflow hooks (brandCreated, brandUpdated) for other plugins to build on

Installation

npm install @mgtalabs/medusa-brand

Register it in your Medusa application's medusa-config.ts:

1module.exports = defineConfig({
2  // ...
3  plugins: [
4    {
5      resolve: "@mgtalabs/medusa-brand",
6      options: {
7        enableSEO: true,
8        enableFeaturedBrands: true,
9        logoRequired: false,
10      },
11    },
12  ],
13})

Then run migrations to create the brand table and sync the product-brand link:

npx medusa db:migrate

Configuration

Admin API

All routes are under /admin and require the standard Medusa admin authentication — nothing extra to configure.

Brand fields: name, slug (auto-derived from name if omitted), description, short_description, logo_url, logo_file_id, banner_url, banner_file_id, meta_title, meta_description, is_featured, sort_order, status (active/inactive), metadata.

Assigning a brand at product-creation time

1POST /admin/products
2{
3  "title": "...",
4  ...
5  "additional_data": { "brand_id": "brand_123" }
6}

Store API

Public routes, gated by a publishable API key like any other store route.

Events

Subscribe from any plugin:

1// src/subscribers/brand-created.ts
2import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
3
4export default async function brandCreatedHandler({
5  event: { data },
6}: SubscriberArgs<{ id: string }>) {
7  // ...
8}
9
10export const config: SubscriberConfig = { event: "brand.created" }

Extension points

Beyond events, createBrandWorkflow and updateBrandWorkflow expose hooks for synchronous, transactional extensibility:

1import { createBrandWorkflow } from "@mgtalabs/medusa-brand/workflows/create-brand"
2
3createBrandWorkflow.hooks.brandCreated(async ({ brand }, { container }) => {
4  // runs inside the same workflow transaction
5})

The product-brand Module Link itself is also queryable by any other plugin.

Known limitations

• Filtering core's /admin/products or /store/products by brand_id directly is not supported — Medusa doesn't document a way to extend a core route's query validator from a plugin. Use this plugin's own /admin/brands/:id/products / /store/brands/:idOrSlug/products instead.
• /store/.../products returns whatever products are linked regardless of their own publish status — Medusa's Query layer doesn't support filtering by a linked model's property (confirmed against current docs), only by the link table's own columns.
• HTTP-level integration tests for this plugin live in the consuming application's own test suite, not this package's — @medusajs/test-utils's medusaIntegrationTestRunner has an open upstream bug when configured at the plugin level (medusajs/medusa#11863). Module-level tests (moduleIntegrationTestRunner) are unaffected and ship in src/modules/brand/__tests__/.

License

Proprietary — see the workspace root LICENSE. Free during the current evaluation period; see the workspace's docs/architecture.md for the licensing/pricing model.