Order Editing: What This Means for Shopify App Developers

At this year’sShopify Unite, we announced a big change to orders:they can now be edited. As a Shopify Partner, this means you can now modify items on an order in your development stores. This change enables you to use the new order editing APIs to extend what is possible on an order. But it’s also important to understand how edited orders may impact your existing apps.

In this blog post, we’ll walk you through what this means for your apps, and the changes you may want to make to your apps to better support merchants.

Why we introduced order editing

This change has been a long time coming—Shopify was built over a decade ago with the assumption that orders were never going to change. Since then, we’ve learned from our merchants that commerce can be messy and unpredictable, and Shopify needs to be a more flexible platform to accommodate their needs. Since orders interact with so many different processes, frompaymentsto inventory, we had to rethink and rebuild large parts of the platform to support it.

But it’s worth it. Order editing enables merchants to offer a better purchase experience to their customers. It significantly reduces the friction for changing items on an existing order, and opens up further possibilities for developers. This is where partners and apps can really extend what is possible on an order: some use cases include automatically adding gifts to an order, customizing orders, and sending product recommendations post-checkout. If you have an existing app that manages orders in any way, this is also an opportunity to support this enhancement to the platform.

Order editing is currently in beta, and is available for testing in your development store via theUnite 2019 developer preview. It will be released to all merchants this year, so now is the time to get familiar with how it works, how it impacts your current apps, and how you can take advantage of it with future builds.

You might also like:Every API We Announced at Shopify Unite 2019.

Order editing APIs: A workflow-based GraphQL interface

We built the UI for order editing in the Shopify Admin using a new set ofGraphQL APIs. We designed these APIs to support each step in the workflow of editing an order, with the complicated price recalculations and updates to other resources handled server-side. You will also be able to leverage this to build your own apps that edit orders.

Specifically, editing an order means editingitemson the order. Existing items can be removed or have their quantity adjusted, and new product variants or custom items can be added to the order. Our backend handles all necessary updates to order totals, tax calculations, and where inventory is sourced from or released back to. Also sent are notifications to the customer, including a checkout link to collect payment for order edits where the order total has increased. You can read ourAPI guidefor full details on how to use these new APIs, or watch our talk from Shopify Unite below.

The impact of order editing on existing APIs

虽然结构和可用的属性existing APIs have not been changed, it’s important to understand that after an order is edited, certain attributes may be updated. Any request to our APIs regarding orders will always respond with the latest information for an order. This includes any edits that may have occurred.

1. Orders API

Order editing will primarily update the Order resource, so it’s important to ensure that your app is aware of any changes to attributes that could impact functionality. Any price-related attributes, such astotal_priceandtotal_tax, may be increased due to new items or item quantities being added to the order. In addition to this, updates toline_itemsare the most important to be aware of. New line items may now be added to the order and existing item quantities changed.

2. Refunds

Items that have been removed from an order as part of an edit will appear asOrder.refunds. If your app does not already consider items that have been refunded, consider doing so if this could impact the functionality of your app. For example, if your app handles order fulfillment in some way, it should be aware that items refunded on an order should not be shipped out.

3. Webhooks

Theorders/updatedwebhook will be sent when an order is edited. This is the recommended way for your app to be aware that information on an order has been updated in some way, including any edits to items on the order. Additional webhooks that may also be triggered on an order edit includerefunds/createandinventory_levels/update.

Determine if your app requires updates

If your app does not currently handle changes to order total amounts and line items after an update, or does not consider refunded items, you may need to update your app if there is a possibility of these changes impacting its functionality. Test order editing on a development preview enabled store with your app and see if there is any unexpected or incorrect behavior.

The best way for your app to keep updated on order edits is to listen for theorders/updatedwebhook, and ensure that at a minimum you update the following attributes in your app if necessary. The following reference is to the REST Admin API, but would apply in a similar way to the GraphQL Admin API.

• Order.financial_status
• Order.fulfillment_status
• Order.line_items
• Order.refunds
• Order.subtotal_price
• Order.subtotal_price_set
• Order.tax_lines
• Order.total_discounts
• Order.total_discounts_set
• Order.total_line_items_price
• Order.total_line_items_price_set
• Order.total_price
• Order.total_price_set
• Order.total_tax
• Order.total_tax_set
• Order.total_weight
• Order.updated_at

In general, our recommended best practice is that for any function of your app that may be affected by an order attribute, you treat the attribute as potentially subject to updates. We will continuously be considering further enhancements and feature additions to what can be done with order editing on our platform, so following these best practices will ensure your app is compatible in the future.

“一般来说,我们推荐的最佳实践for any function of your app that may be affected by an order attribute, you treat the attribute as potentially subject to updates."

Managing fulfillments

If your app manages fulfillments in any way, it is especially important that you support edits to the order done by the merchant. Knowing the exact items on the order and what should be shipped is crucial to avoid errors and ensure the right products are delivered.

We covered how to make sure your apps are compatible with order edits in this article. In addition, at this year’s Shopify Unite we announcednew Fulfillment APIsthat we recommend using. These APIs fully support updates to items due to order edits, and can streamline how your app consumes updated order information that affects items to be fulfilled. Read more about our new Fulfillment APIsin the Help Center.

You might also like:How to Build Multilingual Shopify Apps.

Better customer relationships throughout the ordering process

Order editing is a key platform feature for merchants to ensure a great customer experience. Many merchants will no longer have to say no when a customer requests a change to their order. This can not only prevent a sale from being lost, but also keep that customer coming back.

By ensuring your existing apps handle orders correctly, you will be ready to support merchants offering this to their customers. This fundamental change also opens up more possibilities and flexibility on what can be done on an order, allowing Shopify Developers to extend on what will be initially provided to merchants.

If you have any questions or feedback about getting your app ready for this update, don’t hesitate to reach out in theAPI forums.