Migrate to fulfillment orders

In Shopify, the FulfillmentOrder object models an end-to-end fulfillment process and is available in the GraphQL Admin API. The FulfillmentOrder object enables fulfillment data to sync accurately between Shopify and apps.

This guide describes how to migrate your app to use fulfillment orders to manage fulfillments.

Requirements

Anchor link to section titled "Requirements"

You've built an order management or fulfillment service app.
Your app is using the Fulfillment and Order API objects to fulfill orders, instead of the FulfillmentOrder object.

Step 1: Determine the permissions your app requires

Anchor link to section titled "Step 1: Determine the permissions your app requires"

To migrate your app, you need to update your app's permissions. The permissions that you request depend on the type of app that you've built and the access to fulfillment orders associated with the types of locations that your app needs.

Types of apps

Anchor link to section titled "Types of apps"

You can create the following types of apps:

Type of app	Permissions
Order management app	Manage fulfillment orders assigned to merchant-managed locations: `read_merchant_managed_fulfillment_orders` `write_merchant_managed_fulfillment_orders` Manage fulfillment orders assigned to locations managed by other fulfillment services: `read_third_party_fulfillment_orders` `write_third_party_fulfillment_orders`
Fulfillment service app	Manage fulfillment orders assigned to locations belonging to the app: `read_assigned_fulfillment_orders` `write_assigned_fulfillment_orders`

Types of locations

Anchor link to section titled "Types of locations"

You can have the following types of locations on a shop:

Type of location	Description
Merchant-managed location	A location that's created by the merchant.
Fulfillment service-managed location	A location that's created by a fulfillment service app. When an app creates a fulfillment service, a new location is automatically created on the shop and associated with that fulfillment service.

Step 2: Update your app's permissions

Anchor link to section titled "Step 2: Update your app's permissions"

When you've determined the additional permissions your app requires, you can update your app for new installations and existing installations.

New installations

Anchor link to section titled "New installations"

For new installations, include the additional scopes in the permissions that your app requests as part of authorization code grant.

Existing installations

Anchor link to section titled "Existing installations"

If your app has the write_fulfillments access scope, then it can request any of the following access scopes: write_assigned_fulfillment_orders, write_merchant_managed_fulfillment_orders, write_third_party_fulfillment_orders.
If your app has the read_fulfillments access scope, then it can request any of the following access scopes: read_assigned_fulfillment_orders,read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders.
If your app has the write_orders access scope, and it doesn't have the read_fulfillments or write_fulfillments access scopes, it means that it's not a fulfillment service, and it doesn't own a dedicated location. As a result, it doesn't need the read_assigned_fulfillment_orders or write_assigned_fulfillment_orders access scopes. Instead, your app can request the write_merchant_managed_fulfillment_orders and write_third_party_fulfillment_orders access scopes.
If your app has the read_orders access scopes, and it doesn't have the read/write_fulfillments access scopes, then it can request the write_merchant_managed_fulfillment_orders and write_third_party_fulfillment_orders access scopes.

Step 3: Opt in to fulfillment orders as a fulfillment service

Anchor link to section titled "Step 3: Opt in to fulfillment orders as a fulfillment service"

Legacy fulfillment services are different from fulfillment services that use fulfillment orders in the following ways:

Shopify doesn't automatically create pending fulfillments for the fulfillment service when fulfillment is requested.
Shopify creates successful fulfillments instead of pending fulfillments for the fulfillment service when a fulfilled order is imported.

The communication pattern between Shopify and the app has changed, and no longer relies on fulfillment/create webhooks. Instead, the communication relies on explicit POSTs to the callback URL and the callback URL handles all fulfillment and cancellation requests.

Before a fulfillment service can switch to the fulfillment order-based workflow, the fulfillment service should be updated to register a callback URL and to implicitly switch to the new workflow. You can use the GraphQL Admin API's fulfillmentServiceUpdate mutation for setting callback_url and fulfillment_orders_opt_in values:

After you've opted in to the fulfillment order-based workflow, the fulfillment service app should act as it's described in Manage fulfillments as a fulfillment service app section.

Step 4: Manage fulfillments using fulfillment orders

Anchor link to section titled "Step 4: Manage fulfillments using fulfillment orders"

After you've updated your app, and opted in legacy fulfillment services to use fulfillment orders, you can start managing fulfillments using fulfillment orders as an order management app or a fulfillment service app.

Next steps

Anchor link to section titled "Next steps"

Learn more about the benefits of adopting fulfillment orders workflows.
Manage fulfillments as an order management app.
Manage fulfillments as a fulfillment service app.
Learn about the recommended workflow for using the GraphQL Admin API to track orders placed through third-party marketplaces.