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.
@@ -187,6 +187,28 @@ STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>
      
      \-
      
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      `oxxoExpiresDays`
+      
+      </Table.Cell>
+      <Table.Cell>
+      
+      The number of days before an OXXO payment expires. Only applicable if you plan to use OXXO as a payment method.
+      
+      </Table.Cell>
+      <Table.Cell>
+      
+      No
+      
+      </Table.Cell>
+      <Table.Cell>
+      
+      `3`
+      
      </Table.Cell>
    </Table.Row>
  </Table.Body>
@@ -303,6 +325,18 @@ Assuming you set the ID of the Stripe Module Provider to `stripe` in `medusa-con
      
      `pp_stripe-promptpay_stripe`
      
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      OXXO Payments (Available since [Medusa v2.12.0](https://github.com/medusajs/medusa/releases/tag/v2.12.0))
+      
+      </Table.Cell>
+      <Table.Cell>
+      
+      `pp_stripe-oxxo_stripe`
+      
      </Table.Cell>
    </Table.Row>
  </Table.Body>
@@ -413,6 +447,18 @@ The Stripe Module Provider supports the following payment types, and the webhook
      
      `{server_url}/hooks/payment/stripe-promptpay_stripe`
      
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      OXXO Payments (Available since [Medusa v2.12.0](https://github.com/medusajs/medusa/releases/tag/v2.12.0))
+      
+      </Table.Cell>
+      <Table.Cell>
+      
+      `{server_url}/hooks/payment/stripe-oxxo_stripe`
+      
      </Table.Cell>
    </Table.Row>
  </Table.Body>
@@ -86,6 +86,28 @@ The Medusa Admin UI may not provide a way to create each of these promotion exam

 ---

+## Promotion Limits
+
+<Note>
+
+The `limit` property is available since [Medusa v2.12.0](https://github.com/medusajs/medusa/releases/tag/v2.12.0).
+
+</Note>
+
+A promotion can have usage limits to restrict how many times it can be used.
+
+There are three ways to limit a promotion's usage:
+
+1. By setting its `limit` property: This limits the total number of times the promotion can be used across all orders.
+2. By setting the [global budget on the promotion's campaign](../campaign/page.mdx#global-budgets): This limits the total spend or usage across all promotions in the campaign.
+3. By setting the [attribute-based budget on the promotion's campaign](../campaign/page.mdx#attribute-based-budgets): This limits the total spend or usage for specific attributes across all promotions in the campaign. For example, limiting the budget for a specific customer group.
+
+All budgets are applied on the promotion. Once a budget is exhausted, the promotion can no longer be applied.
+
+For example, if a promotion has a `limit` of `10` and its campaign has a global budget of `$1000`, the promotion can only be used `10` times or until the total discount given reaches `$1000`, whichever comes first.
+
+---
+
 ## Promotion Rules

 A promotion can be restricted by a set of rules, each rule is represented by the [PromotionRule data model](/references/promotion/models/PromotionRule).