Migrate to fulfillment orders
In Shopify, the
FulfillmentOrder resource models an end-to-end fulfillment process and is available in both the REST Admin API and the GraphQL Admin API. The
FulfillmentOrder resource 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.
RequirementsAnchor link to section titled "Requirements"
- You've built an order management or fulfillment service app.
- Your app is using the
OrderAPI resources to fulfill orders, instead of the
- All of the assigned fulfillments in your app are completed. If you have fulfillments in open or pending states, then contact Partner support for help with the migration.
Step 1: Determine the permissions your app requiresAnchor 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:
|Type of app||Permissions|
|Order management app||
|Fulfillment service app||Manage fulfillment orders assigned to different locations:
Step 2: Update your app's permissionsAnchor link to section titled "Step 2: Update your app's permissions"
New installationsAnchor link to section titled "New installations"
For new installations, include the additional scopes in the permissions that your app requests as part of the OAuth process.
Existing installationsAnchor link to section titled "Existing installations"
For existing installations of your app, you don't need to ask merchants to agree to new permissions if they have already granted
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.
Step 3: Opt in legacy fulfillment servicesAnchor link to section titled "Step 3: Opt in legacy fulfillment services"
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.
You can use the REST Admin API's PUT
fulfillment_services endpoint or the GraphQL Admin API's
fulfillmentServiceUpdate mutation to register a callback URL and opt in a legacy fulfillment services to use fulfillment orders:
Step 4: Temporarily opt-out of fulfillment orders (optional)Anchor link to section titled "Step 4: Temporarily opt-out of fulfillment orders (optional)"
As an emergency rollback measure, you can opt out of fulfillment orders after you’ve opted in. Before you can opt-out, your app must meet the following requirements:
- All fulfillment requests must be rejected.
- All cancellation requests must be accepted.
- 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_ordersendpoint or the GraphQL Admin API's
assignedFulfillmentOrdersconnection doesn’t return any results.
Step 5: Manage fulfillments using fulfillment ordersAnchor link to section titled "Step 5: 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.
- 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.