Your guide to the Fulfillment Orders API migration

The best brands in the world know the secret to a business’s success lies in the fulfillment experience, the million little things that happen behind the scenes that work together to optimize the way products get to buyers. As commerce grows increasingly complex, developers are playing a vital role in making fulfillment work.

Today, merchants—and their buyers—rely on Shopify and Shopify partners to provide a transparent and accurate fulfillment solution that is in sync with the way they do business. Whether merchants are fulfilling orders out of their home, selling through various marketplaces, or shipping out of multiple third party logistics providers all over the world, apps power a range of use cases to meet the diverse needs of merchants.

While using Fulfillment and Order resources to fulfill orders was once considered standard, this legacy behavior is no longer compatible with modern workflows. This holds partners back from a better, more accurate, way to fulfill and manage orders and makes it difficult for merchants to have visibility and control over their inventory and fulfillment.

In 2022, we’re committed to providing the best fulfillment experience, period. That’s why we’re deprecating the current Fulfillment API in the in the 2022-04 release and moving the Shopify platform to our Fulfillment Orders API, to help you model the entire fulfillment process more accurately into its sub-pieces and allow you to unlock new features like local delivery & pickup, fulfillment holds, subscriptions and more.

To help you seamlessly migrate, we’ve crafted a guide that walks you through the process of moving to Fulfillment Orders. Read on to jumpstart your journey to the new age of fulfillment.

Update permissions

To start, you will need to request some additional permissions, based on whether you are building a fulfillment service or order management app.

Fulfillment services app will need:

Permissions for write_assigned_fulfillment_orders. This will helpto manage fulfillment orders assigned to their location.

Order management app will need:

Permissions for merchant_managed_fulfillment_orders, allowing you to manage fulfillment orders assigned to merchant-managed locations. This is particularly helpful if merchants are managing inventory across multiple locations.
Permissions for third_party_fulfillment_orders to manage third-party fulfillment orders on behalf of the merchant.

Tip: Be sure to include these scopes in your app permissions in OAuth for new installs.

Request additional scopes for existing installs

If merchants using your app have already granted read_fulfillments or write_fulfillments, rest easy, asthey will not have to agree to new permissions. Instead, you can request granular access scopes for an individual shop installation.

Testing your app

When you migrate your app to a new API, it's important to make sure your software still functions as described. By testing out Fulfillment Orders in a dev store, you can catch any potential issues before launching on production, saving yourself the hassle of needing to make multiple updates while ensuring merchants have a seamless experience.

You can test the functionality of your app on a dev store by creating test orders with the “Bogus” gateway. If your app is an order management app, you can then fulfill these test orders directly through the API using the updated Fulfillment Orders endpoints. If your app is a fulfillment service, you can use your development store to request fulfillment from your service through the Admin.

If you’re wondering what it might look like once updated, take a look at our sample application detailing how fulfillment and order management is done before and after Fulfillment Orders.

Read our complete migration guide for best practices when migrating to Fulfillment Orders

How these changes help

The Fulfillment Orders API models the end-to-end fulfillment process into detailed sub-pieces, so fulfillment data can sync more accurately between Shopify and an order management app or a 3PL. The Fulfillment Order API tracks the lifecycle of fulfillment work, including open, in-progress, closed, canceled or incomplete, so merchants have a more granular and complete view of their order data in Shopify.

Fulfillment orders also include location data, which Shopify would usually only display to merchants in the Admin. This location information is crucial and details which location should ideally fulfill an order.

Accurately fulfill orders with sales channels

What does this mean for your app? If a merchant is selling a product on a third-party marketplace or sales channel, your app will get the most up-to-date information on the order’s status and help you to accurately fulfill orders at the right time.

Previously, legacy fulfillment services would automatically create pending fulfillments for the fulfillment service when fulfillment is requested. As merchants expand their business to capture orders on various sales channels, this has created issues. In some cases, merchants should not fulfill orders immediately. Instead, there are temporary holds until the gateway successfully captures payment.

With Fulfillment Orders, apps no longer need to rely on webhooks to update fulfillment fields. Instead, Shopify will create successful fulfillments in place of pending fulfillments for the fulfillment service when a fulfilled order is imported.

Manage inventory across multiple locations

Fulfillment orders are always an accurate representation of where an item should be fulfilled from. Shopify now allows variants to be stocked at third-party locations and merchant managed locations at the same time.

This multi-location configuration means that the fulfillment_service on variants is no longer accurately representing the service that is exclusively responsible for fulfillment. Your app must use the “assigned location ID” on any open fulfillment orders to understand definitively who is responsible for fulfilling any given order.

… and much more!

We're always working on new ways to enable partners like you to make the fulfillment process easier. In the future, we plan to launch even more fulfillment and inventory management features that are built with app partners in mind, and will make it even easier for your app to deliver value to merchants and their buyers.

We’re excited for what the future holds for our fulfillment partners and how Fulfillment Orders can unlock a new world of features for your clients. Let us know how you’re building with Fulfillment Orders API or what Shopify can do to help you migrate your existing apps today to provide your clients with better visibility and control of their fulfillment and order data.