export const metadata = { title: Custom Order Display ID, }

{metadata.title}

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

This feature is available since Medusa v2.12.0.

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:

{
  "id": "order_123",
  "display_id": 1,
  // other properties...
}

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:

// other imports...
import { Modules } from "@medusajs/framework/utils"
import { OrderTypes, Context } from "@medusajs/framework/types"

module.exports = defineConfig({
  modules: [
    {
      key: Modules.ORDER,
      options: {
        generateCustomDisplayId: async function (
          order: OrderTypes.CreateOrderDTO,
          sharedContext: Context
        ): Promise<string> {
          // Return your custom display ID
          return `${order.email}-${Date.now()}`
        },
      },
    },
    // other modules...
  ],
  // other configurations...
})

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:

module.exports = defineConfig({
  // other configurations...
  featureFlags: {
    view_configurations: true,
  },
})

This enables the feature's flag.

Next, run the necessary migrations:

npx medusa db:migrate

Then, start the Medusa application:

npm run dev

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