Custom Order Display ID

In this guide, you'll learn how to customize the display ID of orders in Medusa.

Default Display ID#

By default, Medusa stores the display ID of orders in the display_id property of the Order data model. The display ID is a serial integer that starts at 1 and increments with each new order.

For example:

Code
1{2  "id": "order_123",3  "display_id": 1,4  // other properties...5}

Custom Display ID#

In some cases, you might want to use a custom display ID for orders. This is useful for integrating with external systems or providing a more user-friendly order identifier.

The Order data model has a custom_display_id property that stores a custom display ID you generate.

You can define the logic for generating this ID in the generateCustomDisplayId module option set in medusa-config.ts.

For example:

medusa-config.ts
1// other imports...2import { Modules } from "@medusajs/framework/utils"3import { OrderTypes, Context } from "@medusajs/framework/types"4
5module.exports = defineConfig({6  modules: [7    {8      key: Modules.ORDER,9      options: {10        generateCustomDisplayId: async function (11          order: OrderTypes.CreateOrderDTO,12          sharedContext: Context13        ): Promise<string> {14          // Return your custom display ID15          return `${order.email}-${Date.now()}`16        },17      },18    },19    // other modules...20  ],21  // other configurations...22})

In the example above, the generateCustomDisplayId function generates a custom display ID by combining the order's email with the current timestamp.

You can implement any logic to generate a unique and meaningful display ID for your orders.

View Custom Display ID in Medusa Admin#

By default, Medusa Admin displays the display_id in the table on the Orders page. To view the custom display ID in the table, you can enable the view_configurations experimental feature.

To enable this feature, add the following to medusa-config.ts:

medusa-config.ts
1module.exports = defineConfig({2  // other configurations...3  featureFlags: {4    view_configurations: true,5  },6})

This enables the feature's flag.

Next, run the necessary migrations:

yarn
pnpm
npx

Then, start the Medusa application:

yarn
pnpm
npm

Finally, customize the Order view in Medusa Admin to display the custom_display_id property.

Search Orders by Display ID#

The display_id and custom_display_id properties are searchable fields of the Order data model. So, you can search orders by either display ID without any customizations.

The Order Module also defines database indexes on both properties. The index on custom_display_id is unique, so each custom display ID must be unique among orders that aren't deleted.

Search in Medusa Admin#

The search box on the Orders page of Medusa Admin searches the order's searchable fields, including display_id and custom_display_id. So, you can enter an order's display ID or custom display ID in the search box to find it.

Search with the Admin API#

To search orders by display ID with the List Orders API route, pass the display ID or custom display ID in the q query parameter.

For example, using the JS SDK:

Code
1const { orders } = await sdk.admin.order.list({2  q: "ORD-1234",3})

The q parameter performs a case-insensitive partial match on the order's searchable fields, which also include the email and the shipping and billing addresses. For example, searching for 12 returns orders whose display ID is 12, 120, or 1234.

Filter with Query in Customizations#

To retrieve an order by its exact display ID or custom display ID in your customizations, such as an API route or workflow step, use Query and pass the property in filters.

For example:

Code
1const { data: orders } = await query.graph({2  entity: "order",3  fields: ["id", "display_id", "custom_display_id"],4  filters: {5    custom_display_id: "ORD-1234",6  },7})