@mercurjs/docs 2.2.0-rc.1 → 2.2.0-rc.3

package/content/resources/best-practices/api-routes.mdx

@@ -0,0 +1,306 @@
+---
+title: "API routes"
+description: "Thin HTTP adapters — typed request/response generics, Zod validation with createFindParams, filterable fields, middlewares as filters, and queryConfig."
+---
+
+An API route is a thin adapter between HTTP and the rest of the system. Its whole job is: validate the request, run a [workflow](/rc/resources/best-practices/workflows) (for writes) or a [Query](/rc/resources/best-practices/workflows#the-query-engine) (for reads), and shape the response. No business logic lives here.
+
+<Note>
+  Routes are [Medusa file-based API routes](https://docs.medusajs.com/learn/fundamentals/api-routes): a `route.ts` under `src/api/**` exports handlers named after HTTP verbs, and a sibling `middlewares.ts` wires validation and filters. Examples below use a custom **Brand** module exposed under `/admin/brands`.
+</Note>
+
+## Type both the request and the response
+
+Every handler is typed on **both** sides — mirror how Medusa's own routes are written:
+
+- `AuthenticatedMedusaRequest<TBodyOrQuery>` — the generic is the validated **body** (writes) or **query params** (reads) type.
+- `MedusaResponse<TResponse>` — the generic is the **response shape**, so `res.json(...)` is checked and the SDK infers a real return type instead of `unknown`.
+
+```ts title="src/api/admin/brands/route.ts"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+import { createBrandsWorkflow } from "../../../workflows/create-brands"
+import {
+  AdminCreateBrandType,
+  AdminGetBrandsParamsType,
+} from "./validators"
+import { AdminBrandListResponse, AdminBrandResponse } from "./types"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest<AdminGetBrandsParamsType>,
+  res: MedusaResponse<AdminBrandListResponse>
+) => {
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+  const { data: brands, metadata } = await query.graph({
+    entity: "brand",
+    fields: req.queryConfig.fields,
+    filters: req.filterableFields,
+    pagination: req.queryConfig.pagination,
+  })
+
+  res.json({
+    brands,
+    count: metadata!.count,
+    offset: metadata!.skip,
+    limit: metadata!.take,
+  })
+}
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminCreateBrandType>,
+  res: MedusaResponse<AdminBrandResponse>
+) => {
+  const { result } = await createBrandsWorkflow(req.scope).run({
+    input: { brands: [req.validatedBody] },
+  })
+
+  res.json({ brand: result[0] })
+}
+```
+
+<Warning>
+  Don't leave `MedusaResponse` bare. An untyped response means `res.json({...})` accepts anything and the typed SDK resolves that endpoint to an empty/`unknown` response — the exact opposite of the point of the typed client. Always pass the response generic.
+</Warning>
+
+## Only `GET`, `POST`, `DELETE`
+
+<Warning>
+  Mercur routes use **only** `GET`, `POST`, and `DELETE`. There is no `PUT` or `PATCH` — model an update as a `POST` to the resource. Keeping to three verbs is what keeps the typed SDK (`.query` / `.mutate` / `.delete`) consistent across every route.
+</Warning>
+
+| Verb | Meaning | SDK method |
+| --- | --- | --- |
+| `GET` | Read (list or retrieve) | `.query()` |
+| `POST` | Create **and** update | `.mutate()` |
+| `DELETE` | Remove | `.delete()` |
+
+## Validation with Zod + exported types
+
+Validation happens in `middlewares.ts` via `validateAndTransformBody` / `validateAndTransformQuery`, and every schema exports its inferred type so the handler generic and the SDK share one source of truth.
+
+**Bodies** are plain Zod objects:
+
+```ts title="src/api/admin/brands/validators.ts"
+import { z } from "zod"
+
+export const AdminCreateBrand = z.object({
+  name: z.string(),
+  is_active: z.boolean().optional(),
+})
+
+export type AdminCreateBrandType = z.infer<typeof AdminCreateBrand>
+```
+
+**List/read params** use the framework helpers — `createFindParams` (pagination + `fields` + `order`) and `createSelectParams` (retrieve) — rather than a hand-rolled object. This is what wires pagination and field selection consistently across every route:
+
+```ts title="src/api/admin/brands/validators.ts"
+import { createFindParams, createOperatorMap } from "@medusajs/medusa/api/utils/validators"
+
+export const AdminGetBrandsParams = createFindParams({
+  limit: 20,
+  offset: 0,
+}).merge(
+  z.object({
+    // declare the fields that may be filtered on
+    id: z.union([z.string(), z.array(z.string())]).optional(),
+    name: z.string().optional(),
+    is_active: z.boolean().optional(),
+    created_at: createOperatorMap().optional(), // gt/lt/gte/lte ranges
+  })
+)
+
+export type AdminGetBrandsParamsType = z.infer<typeof AdminGetBrandsParams>
+```
+
+The handler then trusts `req.validatedBody` / the validated query to already match those types — never re-validate inside the handler.
+
+## List vs retrieve
+
+A list route (`GET /admin/brands`) and a retrieve route (`GET /admin/brands/:id`) select fields the same way but differ in their params helper and response shape. Retrieve uses `createSelectParams` (field selection only — no pagination or filters) and returns a single entity:
+
+```ts title="src/api/admin/brands/[id]/route.ts"
+export const GET = async (
+  req: AuthenticatedMedusaRequest<AdminGetBrandParamsType>,
+  res: MedusaResponse<AdminBrandResponse>
+) => {
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+  const {
+    data: [brand],
+  } = await query.graph({
+    entity: "brand",
+    fields: req.queryConfig.fields,
+    filters: { id: req.params.id },
+  })
+
+  if (!brand) {
+    throw new MedusaError(MedusaError.Types.NOT_FOUND, `Brand ${req.params.id} not found`)
+  }
+
+  res.json({ brand })
+}
+```
+
+```ts title="src/api/admin/brands/validators.ts — retrieve params"
+import { createSelectParams } from "@medusajs/medusa/api/utils/validators"
+
+export const AdminGetBrandParams = createSelectParams()
+export type AdminGetBrandParamsType = z.infer<typeof AdminGetBrandParams>
+```
+
+Both share the same `defaults` idea but declare them separately in the query config (`list` vs `retrieve`) — see [`queryConfig`](/rc/resources/best-practices/api-routes#queryconfig-and-field-selection) below.
+
+## Filterable fields
+
+`req.filterableFields` is the **parsed, validated filter set** produced by `validateAndTransformQuery` from the query params above. Only fields your validator declares can appear there — an unknown query param is dropped, not passed through. The handler forwards it straight to Query:
+
+```ts
+const { data: brands, metadata } = await query.graph({
+  entity: "brand",
+  fields: req.queryConfig.fields,
+  filters: req.filterableFields, // e.g. { is_active: true, created_at: { gt: ... } }
+  pagination: req.queryConfig.pagination,
+})
+```
+
+<Tip>
+  This is why filtering is declarative and safe: to make a field filterable you add it to the validator; to scope a request you inject onto `req.filterableFields` in middleware (next section). The handler never builds a `where` clause by hand.
+</Tip>
+
+## Middlewares as filters
+
+Middlewares aren't only for validation — they're where you inject **scoping filters** so handlers stay ignorant of the rule. A small middleware writes onto `req.filterableFields`; because the handler already forwards that to Query, the scope is applied without the handler knowing. For example, force `GET /admin/brands` to only ever return active rows:
+
+```ts title="src/api/admin/brands/middlewares.ts"
+import {
+  MedusaRequest,
+  MedusaResponse,
+  MedusaNextFunction,
+} from "@medusajs/framework/http"
+
+const onlyActive = (
+  req: MedusaRequest,
+  _res: MedusaResponse,
+  next: MedusaNextFunction
+) => {
+  req.filterableFields.is_active = true // a column on the brand module itself
+  next()
+}
+
+export const adminBrandsMiddlewares = [
+  {
+    method: ["GET"],
+    matcher: "/admin/brands",
+    middlewares: [
+      validateAndTransformQuery(AdminGetBrandsParams, adminBrandQueryConfig.list),
+      onlyActive,
+    ],
+  },
+]
+```
+
+<Tip>
+  Injecting a filter in middleware means a new route on the same resource is scoped by construction, not by remembering to add a filter. This works with `query.graph` because `is_active` lives on the **brand's own module**.
+</Tip>
+
+<Warning>
+  You can only filter this way on a field that belongs to the entity's **own module**. Filtering by a **linked** module's field (e.g. products by their `brand`) does **not** work with `query.graph` — Query aggregates modules after the fact, so there's no join to filter on. Cross-module filtering requires the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module) and `query.index`.
+</Warning>
+
+## Trust the auth middleware
+
+Authentication and actor resolution happen in middleware (`authenticate`), so by the time your handler runs the actor is already established — **trust it**. Read identity from the request context, never from the body:
+
+```ts
+const userId = req.auth_context.actor_id // set by the authenticate middleware
+```
+
+<Warning>
+  Don't re-derive or re-check identity inside handlers, and don't read user/owner ids from the request body — always take them from `req.auth_context` (or a context object a scoping middleware populated). Trusting the middleware keeps authorization in one place.
+</Warning>
+
+## Vendor routes: `seller_context`
+
+Every route under `/vendor/*` is **already authenticated and seller-scoped** — you don't wire auth yourself. By the time your handler runs, the caller is a verified seller member and the request carries a `req.seller_context` you can trust:
+
+```ts
+export const POST = async (
+  req: AuthenticatedMedusaRequest<VendorCreateOfferType>,
+  res: MedusaResponse
+) => {
+  const sellerId = req.seller_context!.seller_id       // the acting seller
+  const currency = req.seller_context!.currency_code
+  // ...run a workflow scoped to this seller
+}
+```
+
+`req.seller_context` gives you `seller_id`, `currency_code`, and the `seller_member` — all verified, so you never re-check membership in a handler.
+
+<Warning>
+  Never take a `seller_id` from the request body or query to decide ownership — that's caller-supplied. The **only** authoritative seller is `req.seller_context.seller_id`. To scope a vendor list route to the caller's data, add the `filterBySellerId()` middleware and every query is constrained automatically — no per-handler `where`:
+
+  ```ts title="src/api/vendor/offers/middlewares.ts"
+  import { filterBySellerId } from "@mercurjs/core/..."
+
+  {
+    method: ["GET"],
+    matcher: "/vendor/offers",
+    middlewares: [
+      validateAndTransformQuery(VendorGetOffersParams, vendorOfferQueryConfig.list),
+      filterBySellerId(),
+    ],
+  }
+  ```
+</Warning>
+
+## `queryConfig` and field selection
+
+`validateAndTransformQuery` takes a query config that controls which `fields` are selectable, `isList`, and default pagination. The handler reads the resolved selection from `req.queryConfig.fields` and pagination from `req.queryConfig.pagination`.
+
+```ts title="src/api/admin/brands/query-config.ts"
+export const adminBrandQueryConfig = {
+  list: {
+    defaults: ["id", "name", "is_active", "created_at"],
+    isList: true,
+  },
+  retrieve: {
+    defaults: ["id", "name", "is_active"],
+  },
+}
+```
+
+<Warning>
+  **`fields` replaces defaults unless prefixed.** An unprefixed field in the request's `fields` param *replaces* the route's default set; prefix with `+`/`-` to merge (e.g. `+brand.name`) or base fields like `thumbnail` silently drop. This is the `medusa-fields-param` gotcha.
+</Warning>
+
+## Response types
+
+Declare the response shapes next to the route (or in `@mercurjs/types` for shared ones) and use them as the `MedusaResponse` generic — the SDK reads these to type `.query()` / `.mutate()` returns:
+
+```ts title="src/api/admin/brands/types.ts"
+import { PaginatedResponse } from "@medusajs/framework/types"
+
+export interface AdminBrandResponse {
+  brand: BrandDTO
+}
+
+export type AdminBrandListResponse = PaginatedResponse<{
+  brands: BrandDTO[]
+}>
+```
+
+## Checklist for a route
+
+- Handler is thin: validate → run workflow (writes) or `query.graph` (reads) → respond.
+- **Both** generics set: `AuthenticatedMedusaRequest<TBody|TQuery>` and `MedusaResponse<TResponse>` — never a bare `MedusaResponse`.
+- Only `GET` / `POST` / `DELETE` exported; updates are `POST`.
+- Query params built with `createFindParams` / `createSelectParams`; bodies with Zod; inferred types exported.
+- Filterable fields declared in the validator; scoping injected via a `filterableFields` middleware, not inlined.
+- Identity read from `req.auth_context`, never the body. On vendor routes, the authoritative seller is `req.seller_context.seller_id` (set by `ensureSellerMiddleware`); scope reads with `filterBySellerId()`.
+- `fields` prefixed with `+`/`-` to merge; defaults declared in `queryConfig`.
+- No mutations outside a workflow.

package/content/resources/best-practices/custom-fields.mdx

@@ -0,0 +1,241 @@
+---
+title: "Custom fields"
+description: "The full loop — add a custom field in core, render it in the panels with defineCustomFieldsConfig, pull linked data with the link property, and type it end-to-end."
+---
+
+Custom Fields attach extra data to an existing entity (a product, customer, order…) through configuration — 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](/rc/resources/best-practices/module-links) data with the `link` property, and [type it end-to-end](/rc/resources/best-practices/types) so every SDK call carries it.
+
+This page is the best-practices view. For the full storage-side setup see [Custom Fields](/rc/resources/customization/custom-fields).
+
+## Reach for a custom field vs a module
+
+The decision is about the **shape and lifecycle** of the data, not its size.
+
+<CardGroup cols={2}>
+  <Card title="Use a custom field when…" icon="circle-check">
+    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.
+  </Card>
+  <Card title="Build a module when…" icon="cube">
+    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.
+  </Card>
+</CardGroup>
+
+<Warning>
+  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](/rc/resources/best-practices/modules).
+</Warning>
+
+## 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`:
+
+```ts title="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 — 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](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module), not `query.graph`.)
+
+<Warning>
+  **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.
+</Warning>
+
+<Tip>
+  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](/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow) 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.
+</Tip>
+
+### 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:
+
+```tsx title="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" : "—"),
+        },
+      ],
+    },
+  ],
+})
+```
+
+<Note>
+  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.
+</Note>
+
+The `displays` fields follow an add / replace / remove convention keyed by `id`:
+
+- **unknown id** → appends a new read-only row,
+- **built-in id + component** → replaces that field's render,
+- **built-in id + `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 (e.g. a `brand`) in the product's columns and displays without wiring a second query:
+
+```tsx title="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 ?? "-" }],
+    },
+  ],
+})
+```
+
+<Tip>
+  `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.
+</Tip>
+
+<Warning>
+  The link must actually exist as a [module link](/rc/resources/best-practices/module-links) 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.
+</Warning>
+
+## 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 — no per-call casts:
+
+```ts title="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](/rc/resources/best-practices/types#the-scenario-a-custom-field-typed-end-to-end).
+
+## 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.
+
+### 1. 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.
+
+### 2. 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 — no need to touch the route handler:
+
+```ts title="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(),
+      },
+    },
+  ],
+})
+```
+
+### 3. A workflow hook consumes it
+
+Mercur's product create workflow — `createProductsWorkflow` from `@mercurjs/core/workflows` (id `mercur-create-products`) — 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](/rc/resources/best-practices/module-links) the product to a brand — with a compensation function so a failure rolls the link back:
+
+```ts title="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)
+  }
+)
+```
+
+<Note>
+  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.
+</Note>
+
+<Tip>
+  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](/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow).
+</Tip>
+
+<Warning>
+  The hook runs **inside** the workflow, so its mutation still obeys the [one-mutation-per-step + compensation](/rc/resources/best-practices/workflows#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.
+</Warning>
+
+## Checklist
+
+- Data is genuinely one-row-per-parent with no lifecycle → 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 / list, with typed `zone`s.
+- 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 → `additional_data` → `additionalDataValidator` declares the key → a `hooks.<name>` consumer does the work inside the workflow, with compensation. No route/workflow forked.