Extend Product Data Model

In this documentation, you'll learn how to extend a data model of the Product Module to add a custom property.

You'll create a Custom data model in a module. This data model will have a custom_name property, which is the property you want to add to the Product data model defined in the Product Module.

You'll then learn how to:

• Link the Custom data model to the Product data model.
• Set the custom_name property when a product is created or updated using Medusa's API routes.
• Retrieve the custom_name property with the product's details, in custom or existing API routes.

Step 1: Define Custom Data Model#

Consider you have a Hello Module defined in the /src/modules/hello directory.

To add the custom_name property to the Product data model, you'll create in the Hello Module a data model that has the custom_name property.

Create the file src/modules/hello/models/custom.ts with the following content:

src/modules/hello/models/custom.ts
1import { model } from "@medusajs/framework/utils"2
3export const Custom = model.define("custom", {4  id: model.id().primaryKey(),5  custom_name: model.text(),6})

This creates a Custom data model that has the id and custom_name properties.

Step 2: Define Link to Product Data Model#

Next, you'll define a module link between the Custom and Product data model. A module link allows you to form a relation between two data models of separate modules while maintaining module isolation.

Create the file src/links/product-custom.ts with the following content:

src/links/product-custom.ts
1import { defineLink } from "@medusajs/framework/utils"2import HelloModule from "../modules/hello"3import ProductModule from "@medusajs/medusa/product"4
5export default defineLink(6  ProductModule.linkable.product,7  HelloModule.linkable.custom8)

This defines a link between the Product and Custom data models. Using this link, you'll later query data across the modules, and link records of each data model.

Step 3: Generate and Run Migrations#

To reflect the Custom data model in the database, generate a migration that defines the table to be created for it.

Run the following command in your Medusa project's root:

Terminal
❯npx medusa db:generate helloModuleService

Where helloModuleService is your module's name.

Then, run the db:migrate command to run the migrations and create a table in the database for the link between the Product and Custom data models:

Terminal
❯npx medusa db:migrate

A table for the link is now created in the database. You can now retrieve and manage the link between records of the data models.

Step 4: Consume productsCreated Workflow Hook#

When a product is created, you also want to create a Custom record and set the custom_name property, then create a link between the Product and Custom records.

To do that, you'll consume the productsCreated hook of the createProductsWorkflow. This workflow is executed in the Create Product Admin API route

The API route accepts in its request body an additional_data parameter. You can pass in it custom data, which is passed to the workflow hook handler.

Add custom_name to Additional Data Validation#

To pass the custom_name in the additional_data parameter, you must add a validation rule that tells the Medusa application about this custom property.

Create the file src/api/middlewares.ts with the following content:

src/api/middlewares.ts
1import { defineMiddlewares } from "@medusajs/framework/http"2import { z } from "zod"3
4export default defineMiddlewares({5  routes: [6    {7      method: "POST",8      matcher: "/admin/products",9      additionalDataValidator: {10        custom_name: z.string().optional(),11      },12    },13  ],14})

The additional_data parameter validation is customized using defineMiddlewares. In the routes middleware configuration object, the additionalDataValidator property accepts Zod validation rules.

In the snippet above, you add a validation rule indicating that custom_name is a string that can be passed in the additional_data object.

Create Workflow to Create Custom Record#

You'll now create a workflow that will be used in the hook handler.

This workflow will create a Custom record, then link it to the product.

Start by creating the step that creates the Custom record. Create the file src/workflows/create-custom-from-product/steps/create-custom.ts with the following content:

src/workflows/create-custom-from-product/steps/create-custom.ts
1import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"2import HelloModuleService from "../../../modules/hello/service"3import { HELLO_MODULE } from "../../../modules/hello"4
5type CreateCustomStepInput = {6  custom_name?: string7}8
9export const createCustomStep = createStep(10  "create-custom",11  async (data: CreateCustomStepInput, { container }) => {12    if (!data.custom_name) {13      return14    }15
16    const helloModuleService: HelloModuleService = container.resolve(17      HELLO_MODULE18    )19
20    const custom = await helloModuleService.createCustoms(data)21
22    return new StepResponse(custom, custom)23  },24  async (custom, { container }) => {25    const helloModuleService: HelloModuleService = container.resolve(26      HELLO_MODULE27    )28
29    await helloModuleService.deleteCustoms(custom.id)30  }31)

In the step, you resolve the Hello Module's main service and create a Custom record.

In the compensation function that undoes the step's actions in case of an error, you delete the created record.

Then, create the workflow at src/workflows/create-custom-from-product/index.ts with the following content:

src/workflows/create-custom-from-product/index.ts
Show Imports
6import { createCustomStep } from "./steps/create-custom"7
8export type CreateCustomFromProductWorkflowInput = {9  product: ProductDTO10  additional_data?: {11    custom_name?: string12  }13}14
15export const createCustomFromProductWorkflow = createWorkflow(16  "create-custom-from-product",17  (input: CreateCustomFromProductWorkflowInput) => {18    const customName = transform(19      {20        input,21      },22      (data) => data.input.additional_data.custom_name || ""23    )24
25    const custom = createCustomStep({26      custom_name: customName,27    })28
29    when(({ custom }), ({ custom }) => custom !== undefined)30      .then(() => {31        createRemoteLinkStep([{32          [Modules.PRODUCT]: {33            product_id: input.product.id,34          },35          [HELLO_MODULE]: {36            custom_id: custom.id,37          },38        }])39      })40
41    return new WorkflowResponse({42      custom,43    })44  }45)

The workflow accepts as an input the created product and the additional_data parameter passed in the request. This is the same input that the productsCreated hook accepts.

In the workflow, you:

1. Use transform to get the value of custom_name based on whether it's set in additional_data. Learn more about why you can't use conditional operators in a workflow without using transform in this guide.
2. Create the Custom record using the createCustomStep.
3. Use when-then to link the product to the Custom record if it was created. Learn more about why you can't use if-then conditions in a workflow without using when-then in this guide.

You'll next execute the workflow in the hook handler.

Consume Workflow Hook#

You can now consume the productsCreated hook, which is executed in the createProductsWorkflow after the product is created.

To consume the hook, create the file src/workflows/hooks/product-created.ts with the following content:

src/workflows/hooks/product-created.ts
Show Imports
5} from "../create-custom-from-product"6
7createProductsWorkflow.hooks.productsCreated(8	async ({ products, additional_data }, { container }) => {9    const workflow = createCustomFromProductWorkflow(container)10    11    for (const product of products) {12      await workflow.run({13        input: {14          product,15          additional_data,16        } as CreateCustomFromProductWorkflowInput,17      })18    }19	}20)

The hook handler executes the createCustomFromProductWorkflow, passing it its input.

Test it Out#

To test it out, send a POST request to /admin/products to create a product, passing custom_name in additional_data:

Code
1curl -X POST 'localhost:9000/admin/products' \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer {token}' \4--data '{5    "title": "Shoes",6    "options": [7      {8        "title": "Default option",9        "values": ["Default option value"]10      }11    ],12    "shipping_profile_id": "{shipping_profile_id}",13    "additional_data": {14        "custom_name": "test"15    }16}'

Make sure to replace {token} with an admin user's JWT token. Learn how to retrieve it in the API reference.

Also, make sure to replace {shipping_profile_id} with an existing shipping profile's ID. You can retrieve one either from the Medusa Admin dashboard or using the List Shipping Profiles API Route.

The request will return the product's details. You'll learn how to retrieve the custom_name property with the product's details in the next section.

Step 5: Retrieve custom_name with Product Details#

When you extend an existing data model through links, you also want to retrieve the custom properties with the data model.

Retrieve in API Routes#

To retrieve the custom_name property when you're retrieving the product through API routes, such as the Get Product API Route, pass in the fields query parameter +custom.*, which retrieves the linked Custom record's details.

For example:

Code
1curl 'localhost:9000/admin/products/{product_id}?fields=+custom.*' \2-H 'Authorization: Bearer {token}'

Make sure to replace {product_id} with the product's ID, and {token} with an admin user's JWT token.

Among the returned product object, you'll find a custom property which holds the details of the linked Custom record:

Code
1{2  "product": {3    // ...4    "custom": {5      "id": "01J9NP7ANXDZ0EAYF0956ZE1ZA",6      "custom_name": "test",7      "created_at": "2024-10-08T09:09:06.877Z",8      "updated_at": "2024-10-08T09:09:06.877Z",9      "deleted_at": null10    }11  }12}

Retrieve using Query#

You can also retrieve the Custom record linked to a product in your code using Query.

For example:

Code
1const { data: [product] } = await query.graph({2  entity: "product",3  fields: ["*", "custom.*"],4  filters: {5    id: product_id,6  },7})

Learn more about how to use Query in this guide.

Step 6: Consume productsUpdated Workflow Hook#

Similar to the productsCreated hook, you'll consume the productsUpdated hook of the updateProductsWorkflow to update custom_name when the product is updated.

The updateProductsWorkflow is executed by the Update Product API route, which accepts the additional_data parameter to pass custom data to the hook.

Add custom_name to Additional Data Validation#

To allow passing custom_name in the additional_data parameter of the update product route, add in src/api/middlewares.ts a new route middleware configuration object:

src/api/middlewares.ts
1import { defineMiddlewares } from "@medusajs/framework/http"2import { z } from "zod"3
4export default defineMiddlewares({5  routes: [6    // ...7    {8      method: "POST",9      matcher: "/admin/products/:id",10      additionalDataValidator: {11        custom_name: z.string().nullish(),12      },13    },14  ],15})

The validation schema is the similar to that of the Create Product API route, except you can pass a null value for custom_name to remove or unset the custom_name's value.

Create Workflow to Update Custom Record#

Next, you'll create a workflow that creates, updates, or deletes Custom records based on the provided additional_data parameter:

1. If additional_data.custom_name is set and it's null, the Custom record linked to the product is deleted.
2. If additional_data.custom_name is set and the product doesn't have a linked Custom record, a new record is created and linked to the product.
3. If additional_data.custom_name is set and the product has a linked Custom record, the custom_name property of the Custom record is updated.

Start by creating the step that updates a Custom record. Create the file src/workflows/update-custom-from-product/steps/update-custom.ts with the following content:

src/workflows/update-custom-from-product/steps/update-custom.ts
1import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"2import { HELLO_MODULE } from "../../../modules/hello"3import HelloModuleService from "../../../modules/hello/service"4
5type UpdateCustomStepInput = {6  id: string7  custom_name: string8}9
10export const updateCustomStep = createStep(11  "update-custom",12  async ({ id, custom_name }: UpdateCustomStepInput, { container }) => {13    const helloModuleService: HelloModuleService = container.resolve(14      HELLO_MODULE15    )16
17    const prevData = await helloModuleService.retrieveCustom(id)18
19    const custom = await helloModuleService.updateCustoms({20      id,21      custom_name,22    })23
24    return new StepResponse(custom, prevData)25  },26  async (prevData, { container }) => {27    const helloModuleService: HelloModuleService = container.resolve(28      HELLO_MODULE29    )30
31    await helloModuleService.updateCustoms(prevData)32  }33)

In this step, you update a Custom record. In the compensation function, you revert the update.

Next, you'll create the step that deletes a Custom record. Create the file src/workflows/update-custom-from-product/steps/delete-custom.ts with the following content:

src/workflows/update-custom-from-product/steps/delete-custom.ts
Show Imports
5import { HELLO_MODULE } from "../../../modules/hello"6
7type DeleteCustomStepInput = {8  custom: InferTypeOf<typeof Custom>9}10
11export const deleteCustomStep = createStep(12  "delete-custom",13  async ({ custom }: DeleteCustomStepInput, { container }) => {14    const helloModuleService: HelloModuleService = container.resolve(15      HELLO_MODULE16    )17
18    await helloModuleService.deleteCustoms(custom.id)19
20    return new StepResponse(custom, custom)21  },22  async (custom, { container }) => {23    const helloModuleService: HelloModuleService = container.resolve(24      HELLO_MODULE25    )26
27    await helloModuleService.createCustoms(custom)28  }29)

In this step, you delete a Custom record. In the compensation function, you create it again.

Finally, you'll create the workflow. Create the file src/workflows/update-custom-from-product/index.ts with the following content:

src/workflows/update-custom-from-product/index.ts
Show Imports
8import { updateCustomStep } from "./steps/update-custom"9
10export type UpdateCustomFromProductStepInput = {11  product: ProductDTO12  additional_data?: {13    custom_name?: string | null14  }15}16
17export const updateCustomFromProductWorkflow = createWorkflow(18  "update-custom-from-product",19  (input: UpdateCustomFromProductStepInput) => {20    const { data: products } = useQueryGraphStep({21      entity: "product",22      fields: ["custom.*"],23      filters: {24        id: input.product.id,25      },26    })27
28    // TODO create, update, or delete Custom record29  }30)

The workflow accepts the same input as the productsUpdated workflow hook handler would.

In the workflow, you retrieve the product's linked Custom record using Query.

Next, replace the TODO with the following:

src/workflows/update-custom-from-product/index.ts
1const created = when(2  "create-product-custom-link",3  {4    input,5    products,6  }, (data) => 7    !data.products[0].custom && 8    data.input.additional_data?.custom_name?.length > 09)10.then(() => {11  const custom = createCustomStep({12    custom_name: input.additional_data.custom_name,13  })14
15  createRemoteLinkStep([{16    [Modules.PRODUCT]: {17      product_id: input.product.id,18    },19    [HELLO_MODULE]: {20      custom_id: custom.id,21    },22  }])23
24  return custom25})26
27// TODO update, or delete Custom record

Using when-then, you check if the product doesn't have a linked Custom record and the custom_name property is set. If so, you create a Custom record and link it to the product.

To create the Custom record, you use the createCustomStep you created in an earlier section.

Next, replace the new TODO with the following:

src/workflows/update-custom-from-product/index.ts
1const deleted = when(2  "delete-product-custom-link",3  {4    input,5    products,6  }, (data) => 7    data.products[0].custom && (8      data.input.additional_data?.custom_name === null || 9      data.input.additional_data?.custom_name.length === 010    )11)12.then(() => {13  deleteCustomStep({14    custom: products[0].custom,15  })16
17  dismissRemoteLinkStep({18    [HELLO_MODULE]: {19      custom_id: products[0].custom.id,20    },21  })22
23  return products[0].custom.id24})25
26// TODO delete Custom record

Using when-then, you check if the product has a linked Custom record and custom_name is null or an empty string. If so, you delete the linked Custom record and dismiss its links.

Finally, replace the new TODO with the following:

src/workflows/update-custom-from-product/index.ts
1const updated = when({2  input,3  products,4}, (data) => data.products[0].custom && data.input.additional_data?.custom_name?.length > 0)5.then(() => {6  return updateCustomStep({7    id: products[0].custom.id,8    custom_name: input.additional_data.custom_name,9  })10})11
12return new WorkflowResponse({13  created,14  updated,15  deleted,16})

Using when-then, you check if the product has a linked Custom record and custom_name is passed in the additional_data. If so, you update the linked Custom record.

You return in the workflow response the created, updated, and deleted Custom record.

Consume productsUpdated Workflow Hook#

You can now consume the productsUpdated and execute the workflow you created.

Create the file src/workflows/hooks/product-updated.ts with the following content:

src/workflows/hooks/product-updated.ts
1import { updateProductsWorkflow } from "@medusajs/medusa/core-flows"2import { 3  UpdateCustomFromProductStepInput, 4  updateCustomFromProductWorkflow,5} from "../update-custom-from-product"6
7updateProductsWorkflow.hooks.productsUpdated(8	async ({ products, additional_data }, { container }) => {9    const workflow = updateCustomFromProductWorkflow(container)10    11    for (const product of products) {12      await workflow.run({13        input: {14          product,15          additional_data,16        } as UpdateCustomFromProductStepInput,17      })18    }19	}20)

In the workflow hook handler, you execute the workflow, passing it the hook's input.

Test it Out#

To test it out, send a POST request to /admin/products/:id to update a product, passing custom_name in additional_data:

Code
1curl -X POST 'localhost:9000/admin/products/{product_id}?fields=+custom.*' \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer {token}' \4--data '{5    "additional_data": {6        "custom_name": "test 2"7    }8}'

Make sure to replace {product_id} with the product's ID, and {token} with the JWT token of an admin user.

The request will return the product's details with the updated custom linked record.