Draft Orders Architecture Overview
In this document, you’ll learn about draft orders, process around draft orders, and their relation to other entities in the Medusa backend.
Overview
Merchants may need to manually create orders without any involvement from the customer. This can be useful if the order is being created through a channel that isn’t integrated within your commerce system, or for some reason the customer can’t create the order themselves.
In Medusa, these types of orders are called draft orders. An admin or a merchant can create a draft order that holds all the details of the order. Then, the draft order can be later transformed into an actual order.
DraftOrder Entity Overview
Some of the DraftOrderCopy to Clipboard's attributes include:
statusCopy to Clipboard: a string indicating the status of the draft order. Its values can be:openCopy to Clipboard: the draft order is created, but hasn’t been completed.completedCopy to Clipboard: the draft order is completed. A draft order is considered completed when the payment for the order has been captured and an order has been created from the draft order.
display_idCopy to Clipboard: a string that can be used as the displayed ID to customers and merchants.canceled_atCopy to Clipboard: a date indicating when the draft order was canceled.completed_atCopy to Clipboard: a date indicating when the draft order was completed.no_notification_orderCopy to Clipboard: a boolean indicating whether the customer should receive notifications when the order is updated.
There are other important attributes discussed in later sections. Check out the full DraftOrder entity in the entities reference.
How Draft Orders Work
You have full freedom in how you choose to implement creating draft orders. This section explains how it’s created in the Medusa backend using the Create Draft Order and Register Payment endpoints.
A draft order is created using the DraftOrderServiceCopy to Clipboard's create method. Within that method, a cart is created along with it. The cart is used to store the order’s details, such as the draft order’s items, shipping options, and more. The cart has the type draft_orderCopy to Clipboard.
Since the draft order is associated with a cart, the process implemented in the Medusa backend around completing the draft order is pretty similar to that of completing a cart.
The payment must be authorized before the cart can be completed, which can be done using the CartServiceCopy to Clipboard's authorizePayment method. Once the payment is authorized, the order can be created using the OrderServiceCopy to Clipboard's createFromCart method.
In the Register Payment endpoint, the systemCopy to Clipboard payment method is used by default as the payment session of the cart. This means that the authorization and capturing of the payment don’t actually trigger any processes with existing payment processors integrated into your Medusa backend. It’s expected that the merchant will handle these processes manually.
The draft order can then be completed using the DraftOrderServiceCopy to Clipboard's registerCartCompletion method. This would update its status to completedCopy to Clipboard and would set the order_idCopy to Clipboard attribute of the draft order. Finally, you can capture the payment of the order that was created using the OrderServiceCopy to Clipboard's capturePayment method.
Once the order is created and the draft order is completed, the created order can be processed and handled the same as orders created by customers.
Relation to Other Entities
Cart
A draft order is associated with a cart that is used to set the items in the draft order, shipping method, and more. A cart is represented by the CartCopy to Clipboard entity.
You can access the ID of the draft order’s cart using the cart_idCopy to Clipboard attribute. You can also access the cart by expanding the cartCopy to Clipboard relation and accessing draft_order.cartCopy to Clipboard.
Order
A draft order is associated with an order that is created once the draft order is completed. An order is represented by the OrderCopy to Clipboard entity.
You can access the ID of the order using the order_idCopy to Clipboard attribute. You can also access the order by expanding the orderCopy to Clipboard relation and accessing draft_order.orderCopy to Clipboard.