feat(product-category): add external_id to product-category (#14799)

## Summary

**What** — What changes are introduced in this PR?

This PR adds `external_id` to the `product-category` type. 
It is available on both /admin and /store, and can be used as filter.


**Why** — Why are these changes relevant or necessary?  

To facilitate runtime lookup from values derived from 3rd party systems (PIM, ERP, Recommendations, CMS-stored-references) of the product-category.

Allows addressing data via its native/real-world identifier, rather than synthetic/instance-specific database identifier.

**How** — How have these changes been implemented?

Added migration to add field. Added field to schemas and queryInfo blocks. 

**Testing** — How have these changes been tested, or how can the reviewer test the feature?

Integration tests included.

---

## Examples


Provide examples or code snippets that demonstrate how this feature works, or how it can be used in practice.  
This helps with documentation and ensures maintainers can quickly understand and verify the change.
```ts
await sdk.admin.productCategory.create({
   name: 'test-category',
   external_id: 'my-external_id'
});
```



```ts
sdk.store.category.list({
   external_id: 'my-external_id'
});
```

---

## Checklist

Please ensure the following before requesting a review:

- [X] I have added a **changeset** for this PR
    - Every non-breaking change should be marked as a **patch**
    - To add a changeset, run `yarn changeset` and follow the prompts
- [X] The changes are covered by relevant **tests**
- [X] I have verified the code works as intended locally
- [X] I have linked the related issue(s) if applicable

---

## Additional Context

Add any additional context, related issues, or references that might help the reviewer understand this PR.


---

> [!NOTE]
> **Medium Risk**
> Adds a new nullable DB column and threads it through admin/store API validation, default field selection, and filtering, which could affect migrations and query behavior. Changes are straightforward but touch persisted schema and public API responses.
> 
> **Overview**
> Product categories now support a nullable `external_id`, persisted via a new MikroORM migration and model/schema update.
> 
> The admin and store APIs include `external_id` in default query fields, accept it on create/update payloads, and allow filtering by it (validators and types updated accordingly).
> 
> Integration tests are expanded/added to cover returning `external_id`, creating/updating it, and filtering by it across module, admin HTTP, and store HTTP routes.
> 
> <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 2872ea5. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>

Author: asgerjensen

.changeset/yummy-teams-matter.md

@@ -0,0 +1,8 @@
+---
+"@medusajs/product": patch
+"integration-tests-http": patch
+"@medusajs/types": patch
+"@medusajs/medusa": patch
+---
+
+add external_id to product-category

integration-tests/http/__tests__/product-category/admin/product-category.spec.ts

@@ -53,6 +53,7 @@ medusaIntegrationTestRunner({
               name: "category-0",
               parent_category_id: productCategoryParent.id,
               rank: 0,
+              external_id: "ext-id-0",
               description: "category-0",
             },
             adminHeaders
@@ -110,6 +111,7 @@ medusaIntegrationTestRunner({
             id: productCategory.id,
             name: productCategory.name,
             handle: productCategory.handle,
+            external_id: productCategory.external_id,
             parent_category_id: productCategoryParent.id,
             category_children: [
               expect.objectContaining({
@@ -226,6 +228,7 @@ medusaIntegrationTestRunner({
             "/admin/product-categories",
             {
               name: "sweater",
+              external_id: "ext-id-sweater",
               parent_category_id: productCategoryParent.id,
               is_internal: true,
             },
@@ -365,6 +368,8 @@ medusaIntegrationTestRunner({
         expect(response.data.product_categories).toHaveLength(7) // created in beforeEach
       })
 
+
+
       it("gets list of product category with immediate children and parents", async () => {
         // BREAKING: To get the children tree, the query param include_descendants_tree must be used
         const path = `/admin/product-categories?limit=7`
@@ -638,6 +643,18 @@ medusaIntegrationTestRunner({
         )
       })
 
+      it('filters based on external id', async () => {  
+
+        const response = await api.get(
+          `/admin/product-categories?external_id=${productCategory.external_id}`,
+          adminHeaders
+        ) 
+
+        expect(response.status).toEqual(200)
+        expect(response.data.product_categories).toHaveLength(1)
+        expect(response.data.product_categories[0].id).toEqual(productCategory.id)
+      });
+
       it("filters based on parent category", async () => {
         const response = await api.get(
           `/admin/product-categories?parent_category_id=${productCategoryParent.id}&limit=7`,
@@ -839,6 +856,46 @@ medusaIntegrationTestRunner({
         )
       })
 
+      it("successfully creates a product category with an external id", async () => {
+        const payload = {
+          name: "test",
+          handle: "test",
+          is_internal: true,
+          parent_category_id: productCategory.id,
+          description: "test",
+          external_id: "ext-id-0",
+        }
+
+        const response = await api.post(
+          `/admin/product-categories`,
+          payload,
+          adminHeaders
+        )
+
+        expect(response.status).toEqual(200)
+        expect(response.data).toEqual(
+          expect.objectContaining({
+            product_category: expect.objectContaining({
+              name: payload.name,
+              description: payload.description,
+              handle: payload.handle,
+              is_internal: payload.is_internal,
+              is_active: false,
+              external_id: payload.external_id,
+              created_at: expect.any(String),
+              updated_at: expect.any(String),
+              parent_category: expect.objectContaining({
+                id: productCategory.id,
+              }),
+              category_children: [],
+              rank: 0,
+            }),
+          })
+        )
+      })
+
+
+
       it("successfully creates a product category with a rank", async () => {
         const payload = {
           name: "test",
@@ -1202,6 +1259,7 @@ medusaIntegrationTestRunner({
             handle: "test",
             is_internal: true,
             is_active: true,
+            external_id: "ext-id-2",
             parent_category_id: productCategory.id,
           },
           adminHeaders
@@ -1220,6 +1278,7 @@ medusaIntegrationTestRunner({
               parent_category_id: productCategory.id,
               category_children: [],
               rank: 1,
+              external_id: "ext-id-2",
             }),
           })
         )

integration-tests/http/__tests__/product-category/store/product-category.spec.ts

@@ -0,0 +1,145 @@
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { IStoreModuleService } from "@medusajs/types"
+import {
+    Modules
+} from "@medusajs/utils"
+import qs from "qs"
+import {
+    adminHeaders,
+    createAdminUser,
+    generatePublishableKey,
+    generateStoreHeaders,
+} from "../../../../helpers/create-admin-user"
+import { createAuthenticatedCustomer } from "../../../../modules/helpers/create-authenticated-customer"
+
+jest.setTimeout(30000)
+
+medusaIntegrationTestRunner({
+  testSuite: ({ dbConnection, api, getContainer }) => {
+    let store
+    let appContainer
+    let productCategory1
+    let productCategory2
+    let storeHeaders
+    let publishableKey
+    let storeHeadersWithCustomer
+    let customer
+
+    const createCategory = async (data, productIds) => {
+      const response = await api.post(
+        "/admin/product-categories",
+        data,
+        adminHeaders
+      )
+
+      await api.post(
+        `/admin/product-categories/${response.data.product_category.id}/products`,
+        { add: productIds },
+        adminHeaders
+      )
+
+      const response2 = await api.get(
+        `/admin/product-categories/${response.data.product_category.id}?fields=*products`,
+        adminHeaders
+      )
+
+      return response2.data.product_category
+    }
+
+
+    beforeEach(async () => {
+      appContainer = getContainer()
+      publishableKey = await generatePublishableKey(appContainer)
+      storeHeaders = generateStoreHeaders({ publishableKey })
+      await createAdminUser(dbConnection, adminHeaders, appContainer)
+      const result = await createAuthenticatedCustomer(api, storeHeaders, {
+        first_name: "tony",
+        last_name: "stark",
+        email: "tony@stark-industries.com",
+      })
+
+      customer = result.customer
+      storeHeadersWithCustomer = {
+        headers: {
+          ...storeHeaders.headers,
+          authorization: `Bearer ${result.jwt}`,
+        },
+      }
+
+      const storeModule: IStoreModuleService = appContainer.resolve(
+        Modules.STORE
+      )
+      // A default store is created when the app is started, so we want to delete that one and create one specifically for our tests.
+      const defaultId = (await api.get("/admin/stores", adminHeaders)).data
+        .stores?.[0]?.id
+      if (defaultId) {
+        await storeModule.deleteStores(defaultId)
+      }
+
+      store = await storeModule.createStores({
+        name: "New store",
+        supported_currencies: [
+          { currency_code: "usd", is_default: true },
+          { currency_code: "dkk" },
+        ],
+      })
+
+    })
+
+    describe("Get product-categories based on publishable key", () => {
+
+      beforeEach(async () => {
+
+        productCategory1 = await createCategory(
+          { name: "test", is_internal: false, is_active: true, external_id: "ext-id-1" },
+          []
+        )
+
+
+        productCategory2 = await createCategory(
+          { name: "test2", is_internal: false, is_active: true, handle: 'test-2', external_id: "ext-id-2" },
+          []
+        )
+      })
+
+       it("returns the external_id on id lookups", async () => {
+        const response = await api.get(
+          `/store/product-categories/${productCategory1.id}`,
+          storeHeaders
+        )
+
+        expect(response.status).toBe(200)
+        expect(response.data.product_category).toEqual(
+          expect.objectContaining({
+            id: productCategory1.id,
+            external_id: "ext-id-1",
+          })
+        )
+      })
+
+      it("it filters on the external_id field", async () => {
+
+
+
+        const searchParam = qs.stringify({
+            external_id: "ext-id-2",
+        })
+
+        const response = await api.get(
+          `/store/product-categories?${searchParam}`,
+          storeHeaders
+        )
+
+        expect(response.status).toBe(200)
+        expect(response.data.product_categories).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: productCategory2.id,
+              external_id: "ext-id-2",
+            }),
+          ])
+        )
+      })      
+    })
+  },
+})

packages/core/types/src/http/product-category/admin/payloads.ts

@@ -30,6 +30,10 @@ export interface AdminCreateProductCategory {
    * The category's ranking among its sibling categories.
    */
   rank?: number
+  /**
+   * An external identifier for the product category.
+   */
+  external_id?: string | null
   /**
    * Key-value pairs of custom data.
    */
@@ -68,6 +72,10 @@ export interface AdminUpdateProductCategory {
    * The category's ranking among its sibling categories.
    */
   rank?: number
+  /**
+   * An external identifier for the product category.
+   */
+  external_id?: string | null
   /**
    * Key-value pairs of custom data.
    */

packages/core/types/src/http/product-category/common.ts

@@ -32,6 +32,10 @@ export interface BaseProductCategory {
    * The category's ranking among sibling categories.
    */
   rank: number | null
+  /**
+   * An external identifier for the product category.
+   */
+  external_id: string | null
   /**
    * The ID of the category's parent.
    */
@@ -93,6 +97,10 @@ export interface BaseProductCategoryListParams
    * Filter by the category's handle(s).
    */
   handle?: string | string[]
+  /**
+   * Filter by the category's external ID(s).
+   */
+  external_id?: string | string[] | null
   /**
    * Filter by whether the category is active.
    */

packages/core/types/src/product/common.ts

@@ -310,6 +310,10 @@ export interface ProductCategoryDTO {
    * The ranking of the product category among sibling categories.
    */
   rank: number
+  /**
+   * An external identifier for the product category, such as an ID from a third-party system.
+   */
+  external_id: string | null
   /**
    * The ranking of the product category among sibling categories.
    */
@@ -384,6 +388,10 @@ export interface CreateProductCategoryDTO {
    * The ID of the parent product category, if it has any.
    */
   parent_category_id?: string | null
+  /**
+   * An external identifier for the product category, such as an ID from a third-party system.
+   */
+  external_id?: string | null
   /**
    * Holds custom data in key-value pairs.
    */
@@ -431,6 +439,10 @@ export interface UpdateProductCategoryDTO {
    * The ID of the parent product category, if it has any.
    */
   parent_category_id?: string | null
+  /**
+   * An external identifier for the product category, such as an ID from a third-party system.
+   */
+  external_id?: string | null
   /**
    * Holds custom data in key-value pairs.
    */
@@ -1012,6 +1024,10 @@ export interface FilterableProductCategoryProps
    * Filter product categories by whether they're internal.
    */
   is_internal?: boolean
+  /**
+   * Filter product categories by external ID.
+   */
+  external_id?: string | string[] | null
   /**
    * Whether to include children of retrieved product categories.
    */

packages/medusa/src/api/admin/product-categories/query-config.ts

@@ -10,6 +10,7 @@ export const defaults = [
   "is_active",
   "is_internal",
   "rank",
+  "external_id",
   "parent_category_id",
   "created_at",
   "updated_at",
@@ -26,6 +27,7 @@ export const allowed = [
   "is_active",
   "is_internal",
   "rank",
+  "external_id",
   "parent_category_id",
   "created_at",
   "updated_at",

packages/medusa/src/api/admin/product-categories/validators.ts

@@ -26,6 +26,7 @@ export const AdminProductCategoriesParamsFields = z.object({
   description: z.union([z.string(), z.array(z.string())]).optional(),
   handle: z.union([z.string(), z.array(z.string())]).optional(),
   parent_category_id: z.union([z.string(), z.array(z.string())]).optional(),
+  external_id: z.union([z.string(), z.array(z.string()), z.null()]).optional(),
   include_ancestors_tree: booleanString().optional(),
   include_descendants_tree: booleanString().optional(),
   is_internal: booleanString().optional(),
@@ -53,6 +54,7 @@ export const CreateProductCategory = z
     is_internal: z.boolean().optional(),
     is_active: z.boolean().optional(),
     parent_category_id: z.string().nullish(),
+    external_id: z.string().nullish(),
     metadata: z.record(z.unknown()).nullish(),
     rank: z.number().nonnegative().optional(),
   })
@@ -74,6 +76,7 @@ export const UpdateProductCategory = z
     is_internal: z.boolean().optional(),
     is_active: z.boolean().optional(),
     parent_category_id: z.string().nullish(),
+    external_id: z.string().nullish(),
     metadata: z.record(z.unknown()).nullish(),
     rank: z.number().nonnegative().optional(),
   })