Draft Orders Plugin

In this guide, you'll learn about the Draft Orders Plugin and its features.

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.
• Manage items in a draft order, allowing admin users to add, update, or remove items.
• Add shipping methods to draft orders..
• Associate existing customers with draft orders..
• Convert draft orders to regular orders..

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.

To install the Draft Orders Plugin:

1. Run the following command in your Medusa application's directory:

yarn
pnpm
npm

2. Add the plugin to your medusa-config.ts file:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  plugins: [4    {5      resolve: "@medusajs/draft-order",6      options: {},7    },8  ],9})

Test the Draft Orders Plugin#

To test the Draft Orders Plugin, start the Medusa application with the following command:

yarn
pnpm
npm

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 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 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 apply to draft orders as well.

Editing Draft Orders#

Similar to regular orders, draft orders can be edited, 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 is incremented.

Calculated Shipping Options#

Draft orders support calculated shipping options, in addition to flat-rate options. When you add a calculated shipping method to a draft order edit using addDraftOrderShippingMethodsWorkflow, Medusa calls the fulfillment provider to price the method against the order's projected items.

Medusa automatically keeps calculated shipping prices up to date during the edit:

• When items are added or removed, Medusa reprices any pending calculated shipping methods against the updated projected items.
• When the edit is confirmed, Medusa reprices any already-applied calculated shipping methods against the final materialized order items.

Shipping methods with a custom amount (is_custom_amount: true) and flat-rate methods are never repriced automatically.

The fetchShippingOptionForDraftOrderWorkflow exposes two hooks you can use to inject additional context before the fulfillment provider calculates the price:

• setPricingContext: inject additional pricing context (for example, a location_id) used when resolving flat-rate prices from the Pricing Module. The context is merged with the order's currency_code.
• setCalculatedShippingPricingContext: inject custom context that is forwarded to the fulfillment provider's calculatePrice method when pricing a calculated shipping option. The returned object is merged into the context parameter of calculatePrice; framework-provided properties take precedence on any naming conflict.

The refreshConfirmedDraftOrderShippingMethodsWorkflow and refreshPendingDraftOrderShippingMethodsWorkflow workflows also expose a setCalculatedShippingPricingContext hook for the same purpose when repricing already-applied or pending calculated shipping methods.

Draft Order Locale#

A draft order's locale can be set and updated before converting it to a regular order. All item details in the draft order, such as product titles and descriptions, will be presented in the correct language if translations are available.

When the draft order is converted to a regular order, it retains its locale property. The details of the order items will remain in the specified locale.

Tax Lines and Address Changes#

When you update a draft order's shipping or billing address using the updateDraftOrderWorkflow, Medusa automatically recomputes the draft order's tax lines. This ensures the tax lines reflect the correct tax jurisdiction after the address change.

Whether Medusa recomputes the tax lines depends on the region's automatic_taxes setting:

• If automatic_taxes is enabled, Medusa recomputes the tax lines from the tax provider.
• If automatic_taxes is disabled, the tax lines are not recomputed.

This behavior is different from regular orders: updating a regular order's address using the updateOrderWorkflow does not trigger a tax recomputation.

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.

When converting a draft order using the convertDraftOrderWorkflow, Medusa recomputes the draft order's tax lines before placing the order. This ensures the order never carries stale tax lines, for example from a previous address change. The recomputation also respects the region's automatic_taxes setting.

Admin users can then manage the order like any other regular order, including processing payments and fulfilling items.