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 to check whether the order can be used to create a draft order. If order.paymentStatus is CANCELED, FULLY_REFUNDED, or PARTIALLY_REFUNDED, the order cannot be edited. Otherwise, continue to step 2.
2. Pass the order ID to 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, Set Discounts, and 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. 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. The updated order is now ready for processing, charging or refunding.

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, you can save unfinished draft orders to complete later. To do this, follow these steps:

1. Call the 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 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. This data is used to calculate the available shipping methods.
   2. Call 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 and 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. 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. The new order is now ready for processing, charging or refunding.

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 to check whether the order can be used to create a draft order. If the order.paymentStatus is CANCELED, FULLY_REFUNDED, or PARTIALLY_REFUNDED, the order cannot be duplicated. Otherwise, continue to step 2.
2. Pass the order ID to 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, Set Discounts, and Set Shipping Info.
4. Call Create Order From Draft to convert the draft order into a new order.