About the Draft Orders API

The Draft Orders API acts as a complementary service to the Orders API. 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.

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
• Create a new order from scratch
• Duplicate an existing order

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.