# About the Draft Orders API

The Draft Orders API acts as a complementary service to the [Orders API](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction).
The draft order is a temporary version of a regular order, allowing you to make multiple fine-tuned modifications to line items, discounts, fees, shipping, and more.
When you're happy with the changes made to the draft order, you can then commit it to a new or existing order.

Learn more about the [draft order lifecycle, calculations, and totals](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/lifecycle-calculations-and-totals).

The Draft Orders API eliminates the complexity of manual calculations and catalog lookups by handling these tasks automatically, allowing for a seamless workflow from draft to completed orders.

With the Draft Orders API, you can:
+ Create a draft order that can be reviewed, adjusted, saved, and then finalized into a new and approved order.
+ Generate a draft order based on an existing order, allowing you to make changes without affecting the original order. When you're done, you can commit the draft order to update the original order.
+ Add or update a draft order’s line items.
+ Set or modify a draft order’s discounts, fees, and taxes.
+ Retrieve draft orders for review or to update calculations.
+ Query draft orders and filter by status, date range, order ID, and more.

## Before you begin

It’s important to note the following points before starting to code:
+ It is not possible to pay for a draft order directly. To do so, the draft must first be committed. Then, the updated order can be paid for normally.
+ An order can only have 1 draft order associated with it at any given time. For example, using an order to create a draft order that already exists, is not allowed. Instead, the existing draft order is returned.
+ **Order limitations:**
    + Draft orders can only be created and committed if the currency and weight measurement unit match those used in the site’s business settings.
    + Orders with a `paymentStatus` of `CANCELED`, `FULLY_REFUNDED` or `PARTIALLY_REFUNDED` cannot be used to create a draft order.
    + Orders with subscription items are not editable.
+ **Line item limitations**:
    + Gift card products cannot be edited.
    + Fulfilled items are not editable.
    + Updating prices for items paid with memberships is restricted.
    + To commit a draft order, it must contain at least one line item.
    + A draft order can contain up to 300 line items (catalog and custom combined).

## Use cases

+ [Edit an existing order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/sample-flows)
+ [Create a new order from scratch](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/sample-flows)
+ [Duplicate an existing order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/sample-flows)

##  Terminology

+ **Draft order:** A temporary version of an order, allowing modifications before finalization.
+ **Order:** A customer's completed request to purchase one or more items from an online store. An order holds information about purchased items, price and tax summaries, shipping and billing information, any applied discounts, and the status of payment and fulfillment.
+ **Calculated draft order:** The draft order details calculated with latest changes.
+ **Commit:** The action of finalizing a draft order, making its modifications permanent. Commit a draft order to either update the existing order, or create a regular new order.
+ **Line item:** 1 or more of the same item (product/service/event/fee) in an order; identified by an ID; can be associated with a catalog or a custom item.
+ **Discount:** A reduction applied to the whole order or to a specific item’s price.
+ **Additional fee:** An optional charge added to an order. For example, service fees or a gift-wrapping fee.

@sdk_package_setup

# Sample Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

## Edit an existing order

The ability to edit existing orders is crucial for merchants across various industries. In many cases, buyers change their mind, forget items, or want to change a delivery method.
In these cases you can use the Draft Orders API to save tentative modifications to an existing order and then finalize them. To do this, follow these steps:

1. Pass the order ID to [Get Order Draftability Status](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/get-order-draftability-status) to check whether the order can be used to create a draft order.
   * If `orderDraftable` returns as `true`, continue to step 2.
   * If `orderDraftable` returns as `false`, refer to `nonDraftableReasons` in the response to understand why the order is not draftable.
2. Pass the order ID to [Create Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-draft-order). Save the newly created draft order’s ID from the response: `calculatedDraftOrder.draftOrder.id`.
3. Modify the draft order by passing the draft order ID and other relevant information to any of the editing methods. For example, [Add Line Items To Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/add-line-items-to-draft-order), [Set Discounts](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/set-discounts), and [Set Shipping Info](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/set-shipping-info).
4. After editing the draft order, retrieve and review the final version by passing the draft order ID to [Get Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/get-draft-order). Confirm all changes are there, and that the response does not include calculation errors.
5. To finalize the changes and update the original order, pass the draft order ID to [Commit Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/commit-draft-order). The updated order is now ready for processing, charging or refunding.

![Draft an existing order](https://wixmp-833713b177cebf373f611808.wixmp.com/images/cb969c3275eafa97544c0cc31aede795.png)

## Create a new order from scratch

Use the Draft Orders API when you need flexibility in managing customers’ orders that don't follow the standard online checkout process.
Draft orders are ideal for handling sales made over the phone, in person, via chat, or through other direct channels, as they allow you to manually create and process orders.

The Draft Orders API allows you to add custom items for additional costs or non-inventory products, offer special pricing like discounts or wholesale rates, manage pre-orders, and re-create orders from other sales channels.
And, unlike [Create Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/create-order), you can save unfinished draft orders to complete later.
To do this, follow these steps:

1. Call the [Create Empty Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-empty-draft-order) method. This initializes a new draft order with no pre-existing data. Save the newly created draft order's ID from the response - `calculatedDraftOrder.draftOrder.id`.
2. Pass the draft order ID and relevant information to the [Add Line Items To Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/add-line-items-to-draft-order) method to add products, services or other items to the draft order.
3. To add recipient information and a shipping method to the draft order:
   1. Pass the draft order ID and relevant information to [Set Recipient Info](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/set-recipient-info). This data is used to calculate the available shipping methods.
   2. Call [Set Shipping Info](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/set-shipping-info) with the draft order ID and other information to set the delivery method. If the shipping method is unavailable, the response will include `calculationErrors`.
4. Create custom discounts and custom additional fees by calling [Create Custom Discounts](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-custom-discounts) and [Create Custom Additional Fees](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-custom-additional-fees) respectively. To apply them immediately to the draft order, specify `applyToDraftOrder: true`.
5. After making all your changes to the draft order, retrieve and review the final version by passing the draft order ID to [Get Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/get-draft-order). Confirm all changes are there, and that the response does not include calculation errors.
6. To convert the draft order into a confirmed order, pass the draft order ID to [Create Order From Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-order-from-draft). The new order is now ready for processing, charging or refunding.

![Create a new order from scratch](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e94723c17669325bd79544d693905480.png)

## Duplicate an existing order

A merchant might want to duplicate an order to save time and reduce errors when creating a new order with similar details.
This can be especially useful in cases such as recurring customer purchases, re-orders with slight modifications, or when processing multiple orders with the same products, shipping details, or special pricing.  
Duplicating an order streamlines the workflow by eliminating the need to re-enter all the details manually, ensuring consistency and efficiency in managing customer transactions. To do this, follow these steps:

1. Pass the order ID to [Get Order Draftability Status](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/get-order-draftability-status) to check whether the order can be used to create a draft order.
   * If `orderDraftable` returns as `true`, continue to step 2.
   * If `orderDraftable` returns as `false`, refer to `nonDraftableReasons` in the response to understand why the order is not draftable.
2. Pass the order ID to [Create Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-draft-order). Save the draft order ID from the response.
3. Modify the draft order by passing the draft order ID and other relevant information to any of the editing methods. For example, [Add Line Items To Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/add-line-items-to-draft-order), [Set Discounts](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/set-discounts), and [Set Shipping Info](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/set-shipping-info).
4. Call [Create Order From Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-order-from-draft) to convert the draft order into a new order.

![Duplicating an existing order](https://wixmp-833713b177cebf373f611808.wixmp.com/images/c7db274b2211ba678832125d362ba3cb.png)

# Lifecycle, Calculations, and Totals

## Draft Order Lifecycle

+ After a draft order is created, its status begins as `DRAFT`.
+ For every action performed on a draft order, a corresponding Draft Order [Created](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/draft-order-created)/[Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/draft-order-updated)/[Deleted](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/draft-order-deleted) webhook is triggered.
+ Once a draft order is committed by calling [Commit Draft Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/commit-draft-order), its status changes to `COMMITTED`, and the [Order Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/order-updated) webhook is triggered. The payload includes the changes made to the original order.
+ When a draft order is converted into a new approved order by calling [Create Order From Draft](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/create-order-from-draft), the [Order Approved](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/order-approved) webhook is triggered. This initiates order-related side effects, including inventory updates, tax calculations, and relevant notifications.

![Draft Order Lifecycle](https://wixmp-833713b177cebf373f611808.wixmp.com/images/fa6ce74b7beec6c68741763ecc887ef5.png)

## Order Calculation

When editing an order, the draft order is re-calculated after each action, and reflects the most up-to-date totals and prices.

+ Newly added items, fees, and discounts are fetched with the latest prices.
+ Existing items, discounts, shipping methods and prices, as well as additional fees, keep their original price and are not automatically updated.
+ Taxes are recalculated automatically, unless the order is marked as tax-exempt.

## Order Total and Balance

When a draft order is committed, there are three possible outcomes that can affect the order's total:
1. Order total *increases*.
2. Order total *decreases*.
3. Order total remains *unchanged*.

Changes to the order’s total can affect the order balance, which represents the remaining amount to be paid. This is calculated as the order total minus any paid amounts.

When the order’s balance changes, there are 3 possible outcomes:
1. **Negative balance:** New order total is less than the amount paid. In this case, merchants can refund the difference back to their customers.
2. **Positive balance**: New order total is greater than the amount paid. Merchants can then charge the remaining order amount using appropriate methods.
3. **Zero balance**: New order total equals the amount paid, resulting in no further payment needed. Refunds or adjustments remain possible if applicable.

# Draft Orders: Supported Filters and Sorting

The following table shows field support for filters and sorting
for the Draft Order object:

| Field          | Supported Filters                                                      | Sortable |
|----------------|------------------------------------------------------------------------|----------|
| `status`       | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`                             | Sortable |
| `orderId`      | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`              |          |
| `createdDate`  | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$lt`, `$le`, `$gt`, `$ge` | Sortable |
| `updatedDate`  | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$lt`, `$le`, `$gt`, `$ge` | Sortable |


__Related content:__
[API Query Language](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::a6026c51-be14-4ea6-a108-dcbc36b074fa*fallback::https://dev.wix.com/docs/rest/articles/get-started/api-query-language),
[Query Draft Orders](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::dbfd3ae0-47e3-4b5e-b177-974102a16518slug::query-draft-orders*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/draft-orders/query-draft-orders)