Serial Allocation Plugin for Medusa v2

A comprehensive serial number management plugin for Medusa v2. Track, allocate, and manage serial numbers across your product catalog with full order lifecycle integration.

Features

• Serial Registration — Register serial numbers linked to product variants via SKU matching
• Automatic Allocation — Serials are auto-assigned on order placement or fulfillment
• Automatic Deallocation — Serials are released back to available when orders are cancelled
• Manual Assignment — Assign specific serials to orders from the admin order detail page
• Void Management — Void serials with reason tracking
• Timeline Tracking — Full audit trail of all serial lifecycle events
• Admin Dashboard — Dedicated serials management pages in the Medusa admin
• Order Widget — Serial allocation status displayed directly on order detail pages
• Store API — Customer-facing endpoints to view serials on their orders
• Status Transitions — Enforced valid state transitions (available → allocated → voided)

Installation

npm install @developerx12/serial-allocation

Configuration

Add the plugin to your medusa-config.ts:

import { defineConfig } from "@medusajs/utils"

export default defineConfig({
  modules: [
    {
      resolve: "./serial-allcoaction",
      options: {
        auto_allocate_on_placed: true,
        auto_allocate_on_fulfillment: true,
        auto_deallocate_on_cancel: true,
      },
    },
  ],
})

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | auto_allocate_on_placed | boolean | false | Auto-allocate serials when an order is placed | | auto_allocate_on_fulfillment | boolean | false | Auto-allocate serials when an order is fulfilled | | auto_deallocate_on_cancel | boolean | false | Release serials back to available when an order is cancelled |

Data Models

Serial

| Field | Type | Description | |-------|------|-------------| | id | string | Primary key | | serial_number | string | Unique serial number | | sku | string | Product SKU | | variant_id | string | Product variant ID | | status | enum | available, allocated, voided |

Serial Item (Allocation)

| Field | Type | Description | |-------|------|-------------| | id | string | Primary key | | serial_id | string | Reference to serial | | order_item_id | string | Order item ID | | order_id | string | Order ID | | allocated_at | Date | Allocation timestamp |

Serial Timeline

| Field | Type | Description | |-------|------|-------------| | id | string | Primary key | | serial_id | string | Reference to serial | | event_type | string | created, allocated, deallocated, voided | | metadata | JSON | Event metadata |

Status Transitions

available  →  allocated
allocated  →  available  (deallocate)
allocated  →  voided
voided     →  (terminal)

API Routes

Admin Routes

| Method | Route | Description | |--------|-------|-------------| | GET | /admin/serial | List all serials (filterable by status, SKU, variant, serial_number) | | POST | /admin/serial/register | Register a new serial | | GET | /admin/serial/:id | Get serial detail with items | | DELETE | /admin/serial/:id | Delete an available serial | | POST | /admin/serial/:id/void | Void a serial | | POST | /admin/serial/:id/deallocate | Deallocate a serial | | POST | /admin/serial/:id/assign-order | Assign a serial to an order | | GET | /admin/serial/:id/timeline | Get serial timeline | | GET | /admin/serial/order/:order_id | Get serial status for an order |

Store Routes

| Method | Route | Description | |--------|-------|-------------| | GET | /store/serial | List serials for authenticated customer | | GET | /store/serial/:order_id | Get serials for a specific order |

Admin UI

Serials List Page (/serials)

• View all serials with status badges
• Search by serial number
• Filter by status (available, allocated, voided)
• Deallocate or delete serials from the list
• Navigate to serial detail or register new serial

Serial Detail Page (/serials/:id)

• View serial details (number, SKU, product, timestamps)
• View allocation history
• View full timeline of events
• Actions: Delete, Void, Deallocate, Open Order

Register Page (/serials/register)

• Register new serials by entering serial number and SKU
• Automatically links to product variant via SKU lookup

Order Detail Widget

• Shows serial allocation progress bar on fulfilled orders
• Per-item breakdown with assigned serial numbers
• "Assign Serial" button opens a modal to select and assign available serials
• Filters available serials to match order items

Workflows

| Workflow | Trigger | Description | |----------|---------|-------------| | allocate-on-placed | order.placed | Auto-allocate serials for all order items | | register-serial | order.fulfillment_created | Auto-allocate serials for fulfillment items | | assign-serial-to-order | Manual | Assign a specific serial to an order | | deallocate-serial | Manual / Cancel | Release a serial from an order | | void-serial | Manual | Permanently void a serial | | delete-serial | Manual | Delete an available serial | | auto-assign-serial | Manual | Scan fulfillments and auto-match serials |

Development

# Install dependencies
npm install

# Build the plugin
npm run build

# Development mode
npm run dev

License

MIT