How to Add a Custom Field

Custom fields attach extra data to a built-in entity such as a product, customer, or order through configuration, with no hand-written model or migration. What makes them powerful is the full loop across the stack. You declare the field in core, render it in the panels with defineCustomFieldsConfig, optionally pull in linked-module data with the link property, and type it end-to-end so every SDK call carries it.

This page is the best-practices view. For the full storage-side setup see Custom Fields.

Reach for a custom field vs a module

The decision is about the shape and lifecycle of the data, not its size.

Use a custom field when…

The data is a plain property of one existing record: is_featured on a product, tier on a customer, source on an order. One row per parent, no lifecycle of its own, read alongside the parent.

Build a module when…

The data has its own lifecycle, relates to more than one entity, has many rows per parent, or carries business logic and its own routes. Reviews, tickets, subscriptions.

Custom Fields is strictly one row per parent entity. Forcing a one-to-many or stateful concept into it works until you need a second row or a state transition. If in doubt, model it as a module.

The full loop

1. Declare the field in core

Register the Custom Fields module and describe the field in medusa-config.ts. The module generates the side table, the link, and the schema on db:migrate.

medusa-config.ts

{
  resolve: "@mercurjs/core/modules/custom-fields",
  options: {
    customFields: {
      Product: {
        is_featured: { type: "boolean", nullable: true },
      },
    },
  },
}

The value now lives in the module’s own custom_fields side table. It is linked to the product, readable alongside it through query.graph, and written through additional_data on the entity’s create/update route. Filtering products by a custom-field value is cross-module and needs the Index Module, not query.graph.

Prefer the custom_fields link over stuffing values into metadata. metadata is an untyped JSON bag with no schema, no queryable columns, and no clean extension point. It turns into a dumping ground. The Custom Fields module gives you a real linked table (custom_fields.*) with typed columns you can read and, via the Index Module, filter on, while still being config-only. Reach for metadata only for genuinely throwaway, never-queried scratch data.

Mutations still go through workflows. The panel submits custom-field values under additional_data on the parent’s create/update route, and additional_data is exactly what workflow hooks receive. So the same values you enter in the panel can be consumed by a productsCreated / productUpdated hook to run follow-up logic, persist to the linked table, or trigger side effects. Never write a custom-field value with a direct route write.

2. Render it in the panel with `defineCustomFieldsConfig`

Drop one file per model under the panel’s src/custom-fields/. A single config contributes form fields (edit drawer, submitted under additional_data), read-only displays (detail sections), and list columns. Declare link: "custom_fields" so the module’s data is fetched alongside the product and available to your fields and displays.

apps/vendor/src/custom-fields/product.tsx

import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
import { createFormHelper } from "@mercurjs/dashboard-shared"

type ProductWithCustomFields = { custom_fields?: { is_featured?: boolean } }

const form = createFormHelper<ProductWithCustomFields>()

export default defineCustomFieldsConfig({
  model: "product",
  link: "custom_fields", // fetch custom_fields.* with the product, no hand-written field list
  forms: [
    {
      zone: "edit",
      fields: {
        is_featured: form.define({
          validation: form.boolean().optional(),
          label: "Featured",
          // read the current value from the linked table, not metadata
          defaultValue: (data) => Boolean(data?.custom_fields?.is_featured),
        }),
      },
    },
  ],
  displays: [
    {
      zone: "general",
      fields: [
        {
          id: "is_featured",
          component: ({ data }) => (data.custom_fields?.is_featured ? "Featured" : "-"),
        },
      ],
    },
  ],
})

The zone values are typed. The panel’s codegen scans the host <FormExtensionZone> / <DisplayExtensionZone> usages and emits the valid zones per model into extension-targets.d.ts. zone: "nope" fails tsc. You don’t hand-maintain that list.

The displays fields follow an add / replace / remove convention keyed by id:

Unknown id: appends a new read-only row.
Built-in id with component: replaces that field’s render.
Built-in id with component: null: hides the field.

The extension API `link` property

A custom-field config can also declare module links to fetch alongside the entity with the link property. This is how you surface data from a linked module such as a brand in the product’s columns and displays without wiring a second query.

apps/vendor/src/custom-fields/product.tsx

export default defineCustomFieldsConfig({
  model: "product",
  link: "brand", // fetch brand.* with each product, one or an array of links
  list: {
    columns: [
      // linked data is available on the row, no extra fetch
      { id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name },
    ],
  },
  displays: [
    {
      zone: "general",
      fields: [{ id: "brand", component: ({ data }) => data.brand?.name ?? "-" }],
    },
  ],
})

link replaces the old “remember to add the fields to every fetch” chore. Under the hood the panel reads the registry’s links (getLinks(model)) and merges them into the built-in list, detail, and edit fetches with withLinkFields(fields, links) (+brand.*), so the linked data is present in all three places automatically. There’s no extendFields: declaring the link is what makes its fields available to both columns and displays.

The link must actually exist as a module link and, in the vendor panel, respect the curated-field constraint. The fetch derived from link runs against the vendor product query, which rejects arbitrary *-relation overrides. Declare the link, then reference only its real fields.

3. Type it end-to-end

The rendered value comes back from the API, but the panel’s ProductDTO doesn’t know about is_featured yet. Close the gap with a one-line declaration-merging .d.ts so every SDK endpoint is typed, with no per-call casts.

apps/vendor/src/types/custom-fields.d.ts

import "@medusajs/types"

declare module "@medusajs/types" {
  interface ProductDTO {
    custom_fields?: { is_featured?: boolean }
  }
}

Now product.custom_fields?.is_featured is typed on every sdk.vendor.products.* response. The runtime value is delivered by the link / registry merge above, not a hand-added +field.* (the vendor product query rejects arbitrary *-relation overrides). The mechanics, why merging into the upstream interface flows through, are covered in Types & augmentation.

The full override flow: `additional_data` → route → workflow hook

Rendering and typing a field is only half the story. The reason custom fields submit under additional_data is that it’s the framework’s built-in extension channel: values entered in the panel travel through the entity’s existing API route into the workflow’s hooks, where your own code consumes them, without forking the route or the workflow. This is exactly what a Mercur override looks like. The flow has three links in the chain.

The panel submits under additional_data

You already did this. A defineCustomFieldsConfig edit/create field is submitted as additional_data.<field> on the entity’s create/update request. Nothing else to wire on the frontend.

The route accepts it via additionalDataValidator

The vendor/admin product routes accept an additional_data body param, but each key must be declared or it’s rejected. Register the allowed keys with additionalDataValidator in a middleware, with no need to touch the route handler.

src/api/middlewares.ts

import { defineMiddlewares } from "@medusajs/framework/http"
import { z } from "@medusajs/framework/zod"

export default defineMiddlewares({
  routes: [
    {
      method: "POST",
      matcher: "/vendor/products",
      additionalDataValidator: {
        brand_id: z.string().optional(),
      },
    },
  ],
})

A workflow hook consumes it

Mercur’s product create workflow is createProductsWorkflow from @mercurjs/core/workflows (id mercur-create-products). It is what the vendor route runs, and it exposes a productsCreated hook that runs after the products are created, receiving both the created records and your additional_data. Consume it to perform the real work, here linking the product to a brand, with a compensation function so a failure rolls the link back.

src/workflows/hooks/created-product.ts

import { createProductsWorkflow } from "@mercurjs/core/workflows"
import { StepResponse } from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
import { LinkDefinition } from "@medusajs/framework/types"
import { BRAND_MODULE } from "../../modules/brand"

createProductsWorkflow.hooks.productsCreated(
  async ({ products, additional_data }, { container }) => {
    if (!additional_data?.brand_id) {
      return new StepResponse([], [])
    }

    const link = container.resolve("link")
    const links: LinkDefinition[] = products.map((product) => ({
      [Modules.PRODUCT]: { product_id: product.id },
      [BRAND_MODULE]: { brand_id: additional_data.brand_id },
    }))

    await link.create(links)
    return new StepResponse(links, links)
  },
  // compensation: undo the links if a later step fails
  async (links, { container }) => {
    if (!links?.length) {
      return
    }
    await container.resolve("link").dismiss(links)
  }
)

Mercur’s createProductsWorkflow wraps Medusa’s stock create-products flow and adds the marketplace layer (seller association, attributes, audit trail). Because it re-exposes the validate and productsCreated hooks, you extend the Mercur flow the same way you would a plain Medusa one. Consume its hook, don’t fork it.

This is the override pattern in one sentence: the panel writes to additional_data, the route lets it through via additionalDataValidator, and a hooks.<name> consumer turns it into real behaviour, all additively, without copying or replacing any built-in code. It’s how you extend a Mercur (or Medusa) flow instead of forking it. See Workflows → hooks.

The hook runs inside the workflow, so its mutation still obeys the one-mutation-per-step + compensation rule. Always pair link.create with a link.dismiss compensation. Never do the work in a route handler after the workflow returns. Put it in the hook.

Checklist

Data is genuinely one row per parent with no lifecycle: use a custom field, otherwise a module.
Field registered in medusa-config.ts, db:migrate run, writes go through additional_data on a workflow.
Panel: one defineCustomFieldsConfig per model contributes forms, displays, and list, with typed zones.
Linked-module data pulled in with the link property (not a hand-written second fetch), the link exists and respects vendor field constraints.
Extended fields typed once via a .d.ts merging into the framework DTO, and requested with +…* so they arrive.
The override chain is complete: panel, then additional_data, then additionalDataValidator declares the key, then a hooks.<name> consumer does the work inside the workflow, with compensation. No route or workflow forked.

Next steps

Module links

Relate modules and fetch linked data alongside an entity.

Modules

Model data that has its own lifecycle, rows, and routes.

Workflows & hooks

Extend a built-in flow through its hooks instead of forking it.

Types & augmentation

Type a custom field end-to-end with declaration merging.

How-Tos

Integrations

Deployment

Reach for a custom field vs a module

Use a custom field when…

Build a module when…

The full loop

1. Declare the field in core

2. Render it in the panel with `defineCustomFieldsConfig`

The extension API `link` property

3. Type it end-to-end

The full override flow: `additional_data` → route → workflow hook

Checklist

Next steps

Module links

Modules

Workflows & hooks

Types & augmentation

​Reach for a custom field vs a module

Use a custom field when…

Build a module when…

​The full loop

​1. Declare the field in core

​2. Render it in the panel with defineCustomFieldsConfig

​The extension API link property

​3. Type it end-to-end

​The full override flow: additional_data → route → workflow hook

​Checklist

​Next steps

Module links

Modules

Workflows & hooks

Types & augmentation

Reach for a custom field vs a module

The full loop

1. Declare the field in core

2. Render it in the panel with `defineCustomFieldsConfig`

The extension API `link` property

3. Type it end-to-end

The full override flow: `additional_data` → route → workflow hook

Checklist

Next steps