docs: docs for next release (#13303)

* added draft order plugin docs * fix vale error * added note about draft order being optional * add new shipping option - shipping method link * update user guides * generate * fix github icon * changes to shipping option type * document logger * reorder list * fixes * fixes
2025-08-28 18:49:07 +03:00
parent 94effdcda7
commit d510639193
55 changed files with 1653 additions and 182 deletions
@@ -0,0 +1,112 @@
+import { Prerequisites } from "docs-ui"
+
+export const metadata = {
+  title: `Draft Orders Plugin`,
+}
+
+# {metadata.title}
+
+In this guide, you'll learn about the Draft Orders Plugin and its features.
+
+<Note>
+
+The Draft Orders Plugin was initially only available to Cloud users during its early access phase. It is now available for all Medusa users.
+
+</Note>
+
+## What is the Draft Orders Plugin?
+
+The Draft Orders Plugin is a Medusa plugin that allows admin users to create and manage draft orders on behalf of customers from the Medusa Admin.
+
+The Medusa application already has the foundation to support draft orders, including data models and API routes. This plugin adds a user interface for managing draft orders in the Medusa Admin dashboard.
+
+The Draft Orders Plugin is especially useful for handling customer support scenarios or when a customer places an order offline, such as over the phone or in-store.
+
+### Features
+
+- [Create draft orders from the Medusa Admin.](!user-guide!/orders/draft-orders/create)
+- [Manage items in a draft order, allowing admin users to add, update, or remove items](!user-guide!/orders/draft-orders/manage#manage-draft-orders-items).
+- [Add shipping methods to draft orders.](!user-guide!/orders/draft-orders/manage#manage-draft-orders-shipping-methods).
+- [Associate existing customers with draft orders.](!user-guide!/orders/draft-orders/manage#manage-draft-orders-customer-details).
+- [Convert draft orders to regular orders.](!user-guide!/orders/draft-orders/manage#convert-draft-order-to-regular-order).
+
+---
+
+## Install the Draft Orders Plugin
+
+The Draft Orders Plugin is available in all Medusa applications starting v2.10.0.
+
+For earlier versions, you can install the plugin manually.
+
+<Prerequisites
+  items={[
+    {
+      text: "Medusa application >= v2.4.0",
+      link: "!docs!/learn/installation"
+    }
+  ]}
+/>
+
+To install the Draft Orders Plugin:
+
+1. Run the following command in your Medusa application's directory:
+
+```bash npm2yarn
+npm install @medusajs/draft-order
+```
+
+2. Add the plugin to your `medusa-config.ts` file:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "@medusajs/draft-order",
+      options: {},
+    },
+  ],
+})
+```
+
+### Test the Draft Orders Plugin
+
+To test the Draft Orders Plugin, start the Medusa application with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+If you open the Medusa Admin at `localhost:9000/app` and log in, you'll find an "Orders -> Drafts" sidebar item.
+
+---
+
+## Draft Orders User Guides
+
+To learn how to use the draft order features in the Medusa Admin, refer to the [Draft Orders](!user-guide!/orders/draft-orders) user guides.
+
+---
+
+## How Draft Orders Work
+
+A draft order is stored in the database as a regular order. It is represented by the [Order data model](/references/order/models/Order) with the following properties:
+
+- `status`: Set to `draft` to indicate that the order is a draft.
+- `is_draft_order`: Set to `true` to indicate that the order is a draft order.
+
+So, the same [order concepts](../concepts/page.mdx) apply to draft orders as well.
+
+### Editing Draft Orders
+
+Similar to regular orders, draft orders can be [edited](../edit/page.mdx), allowing admin users to add, update, or remove items, as well as add shipping methods.
+
+When the order edit is confirmed on the draft order, the changes are applied directly to the draft order and its [version](../order-versioning/page.mdx) is incremented.
+
+### Converting Draft Orders to Regular Orders
+
+Once a draft order is finalized and ready for processing, it can be converted to a regular order. This involves:
+
+- Changing its `status` property to `pending`.
+- Changing its `is_draft_order` property to `false`.
+
+Admin users can then manage the order like any other regular order, including processing payments and fulfilling items.
@@ -29,7 +29,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
 ## Order Features

 - [Order Management](./concepts/page.mdx): Store and manage your orders to retrieve, create, cancel, and perform other operations.
- Draft Orders: Allow merchants to create orders on behalf of their customers as draft orders that later are transformed to regular orders.
+- [Draft Orders](./draft-orders/page.mdx): Allow merchants to create orders on behalf of their customers as draft orders that later are transformed to regular orders.
 - [Apply Promotion Adjustments](./promotion-adjustments/page.mdx): Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
 - [Apply Tax Lines](./tax-lines/page.mdx): Apply tax lines to an order's line items and shipping methods.
 - [Returns](./return/page.mdx), [Edits](./edit/page.mdx), [Exchanges](./exchange/page.mdx), and [Claims](./claim/page.mdx): Make [changes](./order-change/page.mdx) to an order to edit, return, or exchange its items, with [version-based control](./order-versioning/page.mdx) over the order's timeline.