docs: docs for next release (#14110)

2025-12-01 20:20:01 +02:00
parent e4513fab88
commit 223ccb4add
24 changed files with 1196 additions and 27 deletions
@@ -0,0 +1,101 @@
+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.
+
+<Note>
+
+This feature is available since [Medusa v2.12.0](https://github.com/medusajs/medusa/releases/tag/v2.12.0).
+
+</Note>
+
+## Default Display ID
+
+By default, Medusa stores the display ID of orders in the `display_id` property of the [Order data model](/references/order/models/Order). The display ID is a serial integer that starts at 1 and increments with each new order.
+
+For example:
+
+```json
+{
+  "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:
+
+```ts title="medusa-config.ts"
+// 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`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // other configurations...
+  featureFlags: {
+    view_configurations: true,
+  },
+})
+```
+
+This enables the feature's flag.
+
+Next, run the necessary migrations:
+
+```bash
+npx medusa db:migrate
+```
+
+Then, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+Finally, customize the Order view in Medusa Admin to display the `custom_display_id` property.