Product attributes

Name: Product attributes
Author: Empty-complete-org

Custom attributes module for Medusa v2 with support for text, number, file types and units of measurement

Featured on Medusa

npm install @empty-complete-org/medusa-product-attributes

Medusa Product Attributes

A flexible attribute system for Medusa v2 — text, number, file, boolean, with units and category inheritance

Features

Feature	Description
Text Attributes	Arbitrary text values for products
Numeric Attributes	Numbers with units (kg, m, pcs, etc.)
File Attributes	File uploads: certificates, 3D models, manuals
Boolean Attributes	Yes/No values
Category Inheritance	Attributes cascade from parent to child categories
Global Attributes	Applied to every product automatically
Templates	Reusable blueprints — apply to any category in one click
Auto Slug	Labels are transliterated (Russian, Chinese, any script)
Smart File Naming	Uploaded images renamed to
i18n	English and Russian out of the box, extensible

Requirements

Dependency	Version
Medusa	^2.13
Node.js	>=20
TypeScript	^5.0

Quick Start

Installation

1# Via pnpm
2pnpm add @empty-complete-org/medusa-product-attributes
3
4# Via npm
5npm install @empty-complete-org/medusa-product-attributes
6
7# Via yarn
8yarn add @empty-complete-org/medusa-product-attributes

1. Add the plugin to configuration

1// medusa-config.ts
2import { defineConfig } from '@medusajs/framework/utils'
3
4export default defineConfig({
5  plugins: [
6    {
7      resolve: "@empty-complete-org/medusa-product-attributes",
8      options: {},
9    },
10  ],
11})

2. Run migrations

npx medusa db:migrate

3. Done!

The plugin automatically creates tables and registers admin widgets.

Screenshots

Product attribute values

Settings — Global Attributes & Templates

Settings page

Usage

Admin

Category attributes — open any category, the "Attributes" widget appears below details. Add custom attributes (inherited by subcategories), or pick from a template.
Global attributes — Settings → Product Attributes → Globals tab. Applied to every product automatically.
Templates — Settings → Product Attributes → Templates tab. Reusable blueprints.
Product values — open any product, the "Characteristics" widget shows all inherited + global attributes with inputs.

API

1GET    /admin/product/:productId/attribute-schema
2GET    /admin/category/:categoryId/custom-attributes
3POST   /admin/category/:categoryId/custom-attributes
4PATCH  /admin/category/:categoryId/custom-attributes
5GET    /admin/global-attributes
6POST   /admin/global-attributes
7PATCH  /admin/global-attributes
8GET    /admin/attribute-templates
9POST   /admin/attribute-templates
10PATCH  /admin/attribute-templates
11POST   /admin/attribute-templates/:id/apply  { category_id }
12GET    /admin/product/:productId/custom-attributes
13POST   /admin/product/:productId/custom-attributes

Storefront (Store API)

The plugin ships a read-only module link between and , so attribute values are queryable straight from the Store API via the parameter — no extra setup in your app:

1GET /store/products?fields=*product_custom_attributes.*,*product_custom_attributes.category_custom_attribute.*
2GET /store/products/:id?fields=*product_custom_attributes.category_custom_attribute.*

carries the attribute metadata (, , , ). The singular alias works as well.

The same relation is available anywhere Query is, e.g. in workflows or API routes:

1const { data: products } = await query.graph({
entity: "product",
fields: [
  "id",
  "title",
  "product_custom_attributes.*",
  "product_custom_attributes.category_custom_attribute.*",
],
9})

Programmatic usage

1import { CUSTOM_ATTRIBUTE_MODULE } from '@empty-complete-org/medusa-product-attributes'
2
3const module = container.resolve(CUSTOM_ATTRIBUTE_MODULE)
4
5// Create a category attribute
6await module.createCategoryAttribute({
7  label: 'Screen Size',
8  type: 'number',
9  unit: 'inch',
10  category_id: 'pcat_phones',
11})
12
13// Add a product value
14await module.createProductAttribute({
15  product_id: 'prod_iphone15pro',
16  category_custom_attribute_id: 'attr_screen_size',
17  value: '6.1',
18  value_numeric: 6.1,
19})

Attribute types

Type	Admin input	Stored in
	text input
	number input + unit badge	,
	upload button	(URL),
	select Yes/No

Project Structure

1medusa-product-attributes/
2├── src/
3│   ├── admin/
4│   │   ├── lib/
5│   │   │   ├── i18n.ts
6│   │   │   ├── locales/
7│   │   │   │   ├── en.json
8│   │   │   │   └── ru.json
9│   │   │   └── sdk.ts
10│   │   ├── routes/settings/product-attributes/
11│   │   │   └── page.tsx
12│   │   └── widgets/
13│   │       ├── category-attribute-templates.tsx
14│   │       └── product-attribute-values.tsx
15│   ├── api/admin/
16│   │   ├── attribute-templates/
17│   │   ├── category/[categoryId]/custom-attributes/
18│   │   ├── global-attributes/
19│   │   └── product/[productId]/
20│   │       ├── attribute-schema/
21│   │       └── custom-attributes/
22│   └── modules/product-attributes/
23│       ├── models/
24│       ├── migrations/
25│       ├── service.ts
26│       └── index.ts
27├── assets/
28├── package.json
29├── tsconfig.json
30└── LICENSE

Development

1pnpm install
2pnpm test              # Jest unit tests
3pnpm run build         # medusa plugin:build
4pnpm run dev           # medusa plugin:develop

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

_{Made with ❤️ for the Medusa community}