Manage fulfillments as an order management app

• Your app can make authenticated requests to the REST Admin API or GraphQL Admin API.
• Your app has the merchant_managed_fulfillment_orders and third_party_fulfillment_orders access scopes. Learn how to configure your access scopes using Shopify CLI.
• Your store has existing orders that are unfulfilled.
  • If you want to create test orders, then refer to Manage test orders.
  • If you need to make changes to an unfulfilled item, then you can edit an order.
• You're familiar with the API objects that pertain to fulfillment orders.
• You've met Shopify's protected customer data requirements.

You can use the REST Admin API's GET fulfillment_orders endpoint or the GraphQL Admin API's order query to retrieve an order and its associated fulfillment orders. To retrieve fulfillment orders, provide the ID of the order in the request.

The response returns information about the associated fulfillment orders, including the fulfillment order ID, fulfillment order line items, supported actions, and assigned locations. Make note of the inventory item ID, as you'll use it to query inventory levels in the next step.

You can use the REST Admin API's GET inventory_items endpoint or the GraphQL Admin API's inventoryItem query to retrieve the inventory levels for items and the locations where the items are stocked.

To retrieve inventory levels, provide the ID of the inventory item in your request:

Each fulfillment order object includes a list of supported fulfillment order actions to determine which actions the app can take. This information is available in the JSON response received in the first step in this guide.

If you're using the GraphQL Admin API, then you can use the order query to independently request information about fulfillment order actions. Provide the order ID to retrieve supported actions:

If a fulfillment order is open, then apps can inspect the list of supported actions and decide what to action to take.

The following table describes the list of supported fulfillment order actions. Each action is used at a different stage in the fulfillment process.

You can use the REST Admin API's POST fulfillment_orders/move endpoint or the GraphQL Admin API's fulfillmentOrderMove mutation to move a fulfillment order from one location to another.

Only fulfillment orders assigned to merchant-managed locations can be moved between locations, and moving a fulfillment order has no impact on the shipping rate that the customer has already paid.

You can use the REST Admin API's POST fulfillments endpoint or the GraphQL Admin API's fulfillmentCreateV2 mutation to create a fulfillment.

In the request, provide the line items, destination, and order information you retrieved in the first step of this guide.

If a merchant is using a third-party fulfillment service, then the service can support the REQUEST_FULFILLMENT action.

You can use the REST Admin API's POST fulfillment_request endpoint or the GraphQL Admin API's fulfillmentOrderSubmitFulfillmentRequest mutation to request a fulfillment with the assigned fulfillment service. Apps can also provide an optional message to facilitate communication with the fulfillment service.

To request a fulfillment for all the line items, you only need to pass the fulfillment order ID in the request:

You can also use the REST Admin API's POST fulfillment_request endpoint or the GraphQL Admin API's fulfillmentOrderSubmitFulfillmentRequest mutation to submit only one of the line items on the fulfillmentOrder for fulfillment.

The following example shows a request to fulfill one fulfillment order line item:

If a merchant is using a third-party fulfillment service, then the service can support the CANCEL_FULFILLMENT_ORDER action.

You can use the REST Admin API's POST fulfillment_orders/cancel endpoint or the GraphQL Admin API's fulfillmentOrderCancel mutation to immediately cancel the fulfillment order.

Fulfillment orders that return the CANCEL_FULFILLMENT_ORDER action have one of the following request statuses:

A merchant might submit a fulfillment request for a fulfillment order. They then receive an email from the customer, who wants to confirm the size of an item. To stop the third-party fulfillment service from accepting the fulfillment order request, the app can cancel the fulfillment order request until the customer confirms the size.

The following example shows how to cancel a fulfillment that's being managed by a third-party fulfillment service:

If a merchant is using a third-party fulfillment service, then the service can support the REQUEST_CANCELLATION action.

You can use the REST Admin API's POST fulfillment_orders/cancellation_request endpoint or the GraphQL Admin API's fulfillmentOrderSubmitCancellationRequest mutation to send a request to the third-party fulfillment service to cancel the fulfillment order.

The following example shows how to send a request to the third-party fulfillment service to cancel the fulfillment order. The response returns that the cancellation request is in progress.

Fulfillment orders that are assigned to an external fulfillment service return EXTERNAL as a supported action.

When dealing with a fulfillment order that's assigned to an external fulfillment service, your app should redirect the merchant to the URL in the externalUrl field to initiate the fulfillment process outside of Shopify.

In API version 2023-01 and higher, your app can subscribe to webhooks for event notifications related to fulfillment orders. The following examples show the JSON responses from each of the available webhooks.

To learn how to set up and consume webhooks, refer to Webhooks configuration overview.

• Learn about the recommended workflow for using Shopify APIs to track orders placed through third-party marketplaces.