Migrate to fulfillment orders

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

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:

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

For new installations, include the additional scopes in the permissions that your app requests as part of the OAuth process.

For existing installations of your app, you don't need to ask merchants to agree to new permissions if they have already granted read_fulfillments or write_fulfillments permissions to your app.

You can use the request_granular_access_scopes REST endpoint to request a subset of granular access scopes for an individual shop installation. The following example request adds a single granular access scope to an existing installation.

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 REST Admin API's PUT fulfillment_services endpoint or 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.

As an emergency rollback measure, you can opt out of fulfillment orders after you’ve opted in. Before you can opt-out, your fulfillment service must meet the following requirements:

• All unprocessed fulfillment requests must be rejected, or accepted and fulfilled.
• All unprocessed cancellation requests must be accepted or rejected.
• All in-progress fulfillment orders that were previously accepted must either have their fulfillment orders closed or their fulfillments created.
• The REST Admin API's GET assigned_fulfillment_orders endpoint or the GraphQL Admin API's assignedFulfillmentOrders connection doesn’t return any results.

You can use the REST Admin API's PUT fulfillment_services endpoint or the GraphQL Admin API's fulfillmentServiceUpdate mutation to set fulfillment_orders_opt_in property back to false (fulfillmentOrdersOptIn in GraphQL).

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.

• 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 Shopify APIs to track orders placed through third-party marketplaces.