read_assigned_fulfillment_orders access scope, read_merchant_managed_fulfillment_orders access scope, read_third_party_fulfillment_orders access scope or read_marketplace_fulfillment_orders access scope.
The FulfillmentOrder object represents either an item or a group of items in an Order that are expected to be fulfilled from the same location. There can be more than one fulfillment order for an order at a given location.
Fulfillment orders represent the work which is intended to be done in relation to an order. When fulfillment has started for one or more line items, a Fulfillment is created by a merchant or third party to represent the ongoing or completed work of fulfillment.
See below for more details on creating fulfillments.
Shopify creates fulfillment orders automatically when an order is created. It is not possible to manually create fulfillment orders.
See below for more details on the lifecycle of a fulfillment order.
Retrieving fulfillment orders
Fulfillment orders from an order
All fulfillment orders related to a given order can be retrieved with the Order.fulfillmentOrders connection.
API access scopes govern which fulfillments orders are returned to clients. An API client will only receive a subset of the fulfillment orders which belong to an order if they don't have the necessary access scopes to view all of the fulfillment orders.
Fulfillment orders assigned to the app for fulfillment
Fulfillment service apps can retrieve the fulfillment orders which have been assigned to their locations with the
assignedFulfillmentOrders
connection.
Use the argument to control whether all assigned fulfillment orders
should be returned or only those where a merchant has sent a
fulfillment request
and it has yet to be responded to.
The API client must be granted the access scope to access
the assigned fulfillment orders.
All fulfillment orders
Apps can retrieve all fulfillment orders with the fulfillmentOrders query. This query returns all assigned, merchant-managed, and third-party fulfillment orders on the shop, which are accessible to the app according to the fulfillment order access scopes it was granted with.
The lifecycle of a fulfillment order
Fulfillment Order Creation
After an order is created, a background worker performs the order routing process which determines which locations will be responsible for fulfilling the purchased items. Once the order routing process is complete, one or more fulfillment orders will be created and assigned to these locations. It is not possible to manually create fulfillment orders.
Once a fulfillment order has been created, it will have one of two different lifecycles depending on the type of location which the fulfillment order is assigned to.
The lifecycle of a fulfillment order at a merchant managed location
Fulfillment orders are completed by creating fulfillments. Fulfillments represents the work done.
For digital products a merchant or an order management app would create a fulfilment once the digital asset has been provisioned. For example, in the case of a digital gift card, a merchant would to do this once the gift card has been activated - before the email has been shipped.
On the other hand, for a traditional shipped order, a merchant or an order management app would create a fulfillment after picking and packing the items relating to a fulfillment order, but before the courier has collected the goods.
Learn about managing fulfillment orders as an order management app.
The lifecycle of a fulfillment order at a location which is managed by a fulfillment service
For fulfillment orders which are assigned to a location that is managed by a fulfillment service, a merchant or an Order Management App can send a fulfillment request to the fulfillment service which operates the location to request that they fulfill the associated items. A fulfillment service has the option to accept or reject this fulfillment request.
Once the fulfillment service has accepted the request, the request can no longer be cancelled by the merchant or order management app and instead a cancellation request must be submitted to the fulfillment service.
Once a fulfillment service accepts a fulfillment request, then after they are ready to pack items and send them for delivery, they create fulfillments with the fulfillmentCreate mutation. They can provide tracking information right away or create fulfillments without it and then update the tracking information for fulfillments with the fulfillmentTrackingInfoUpdate mutation.
Learn about managing fulfillment orders as a fulfillment service.
API access scopes
Fulfillment orders are governed by the following API access scopes:
- The
andaccess scopes grant access to fulfillment orders assigned to merchant-managed locations. - The
andaccess scopes are intended for fulfillment services. These scopes grant access to fulfillment orders assigned to locations that are being managed by fulfillment services. - The
andaccess scopes grant access to fulfillment orders assigned to locations managed by other fulfillment services.
Fulfillment service app access scopes
Usually, fulfillment services have the access scope
and don't have the
or access scopes.
The app will only have access to the fulfillment orders assigned to their location
(or multiple locations if the app registers multiple fulfillment services on the shop).
The app will not have access to fulfillment orders assigned to merchant-managed locations
or locations owned by other fulfillment service apps.
Order management app access scopes
Order management apps will usually request and
access scopes. This will allow them to manage all fulfillment orders
on behalf of a merchant.
If an app combines the functions of an order management app and a fulfillment service, then the app should request all access scopes to manage all assigned and all unassigned fulfillment orders.
Notifications about fulfillment orders
Fulfillment services are required to register a self-hosted callback URL which has a number of uses. One of these uses is that this callback URL will be notified whenever a merchant submits a fulfillment or cancellation request.
Both merchants and apps can subscribe to the fulfillment order webhooks to be notified whenever fulfillment order related domain events occur.
Fields and connections
The fulfillment order's assigned location. This is the location where the fulfillment is expected to happen.
The fulfillment order's assigned location might change in the following cases:
- The fulfillment order has been entirely moved to a new location. For example, the fulfillmentOrderMove mutation has been called, and you see the original fulfillment order in the movedFulfillmentOrder field within the mutation's response.
- Work on the fulfillment order hasn't yet begun, which means that the fulfillment order has the OPEN, SCHEDULED, or ON_HOLD status, and the shop's location properties might be undergoing edits (for example, in the Shopify admin).
ID of the channel that created the order.
Date and time when the fulfillment order was created.
Delivery method of this fulfillment order.
The destination where the items should be sent.
The date and time at which the fulfillment order will be fulfillable. When this date and time is reached, the scheduled fulfillment order is automatically transitioned to open. For example, the
date for a subscription order might be the 1st of each month, a pre-orderdate would benil, and a standard orderdate would be the order creation date.The latest date and time by which all items in the fulfillment order need to be fulfilled.
The fulfillment holds applied on the fulfillment order.
Fulfillment orders eligible for merging with the given fulfillment order.
A list of fulfillments for the fulfillment order.
A globally-unique ID.
The duties delivery method of this fulfillment order.
A list of the fulfillment order's line items.
A list of locations that the fulfillment order can potentially move to.
A list of requests sent by the merchant or an order management app to the fulfillment service for the fulfillment order.
The order that's associated with the fulfillment order.
ID of the order that's associated with the fulfillment order.
The unique identifier for the order that appears on the order page in the Shopify admin and the Order status page. For example, "#1001", "EN1001", or "1001-A". This value isn't unique across multiple stores.
The date and time when the order was processed. This date and time might not match the date and time when the order was created.
The request status of the fulfillment order.
The status of the fulfillment order.
The actions that can be performed on this fulfillment order.
The date and time when the fulfillment order was last updated.
Returns a Fulfillment order resource by ID.
The paginated list of fulfillment orders assigned to the shop locations owned by the app.
Assigned fulfillment orders are fulfillment orders that are set to be fulfilled from locations managed by fulfillment services that are registered by the app. One app (api_client) can host multiple fulfillment services on a shop. Each fulfillment service manages a dedicated location on a shop. Assigned fulfillment orders can have associated fulfillment requests, or might currently not be requested to be fulfilled.
The app must have the
access scope to be able to retrieve the fulfillment orders assigned to its locations.All assigned fulfillment orders (except those with the
status) will be returned by default. Perform filtering with theargument to receive only fulfillment orders that have been requested to be fulfilled.The paginated list of all fulfillment orders. The returned fulfillment orders are filtered according to the fulfillment order access scopes granted to the app.
Use this query to retrieve fulfillment orders assigned to merchant-managed locations, third-party fulfillment service locations, or all kinds of locations together.
For fetching only the fulfillment orders assigned to the app's locations, use the assignedFulfillmentOrders connection.
Returns a list of fulfillment orders that are on hold.
Mutations
Accept a cancellation request sent to a fulfillment service for a fulfillment order.
Accepts a fulfillment request sent to a fulfillment service for a fulfillment order.
Marks a fulfillment order as canceled.
Marks an in-progress fulfillment order as incomplete, indicating the fulfillment service is unable to ship any remaining items and intends to close the fulfillment order.
Applies a fulfillment hold on an open fulfillment order.
Changes the location which is assigned to fulfill a number of unfulfilled fulfillment order line items.
Moving a fulfillment order will fail in the following circumstances:
- The fulfillment order is closed.
- The destination location has never stocked the requested inventory item.
- The API client doesn't have the correct permissions.
Line items which have already been fulfilled can't be re-assigned and will always remain assigned to the original location.
You can't change the assigned location while a fulfillment order has a request status of
,,, or. These request statuses mean that a fulfillment order is awaiting action by a fulfillment service and can't be re-assigned without first having the fulfillment service accept a cancellation request. This behavior is intended to prevent items from being fulfilled by multiple locations or fulfillment services.How re-assigning line items affects fulfillment orders
First scenario: Re-assign all line items belonging to a fulfillment order to a new location.
In this case, the assignedLocation of the original fulfillment order will be updated to the new location.
Second scenario: Re-assign a subset of the line items belonging to a fulfillment order to a new location. You can specify a subset of line items using the
parameter (available as of the2023-04API version), or specify that the original fulfillment order contains line items which have already been fulfilled.If the new location is already assigned to another active fulfillment order, on the same order, then a new fulfillment order is created. The existing fulfillment order is closed and line items are recreated in a new fulfillment order.
Marks a scheduled fulfillment order as open.
Rejects a cancellation request sent to a fulfillment service for a fulfillment order.
Rejects a fulfillment request sent to a fulfillment service for a fulfillment order.
Releases the fulfillment hold on a fulfillment order.
Reschedules a scheduled fulfillment order.
Updates the value of the
field on a scheduled fulfillment order.The fulfillment order will be marked as ready for fulfillment at this date and time.
Sends a cancellation request to the fulfillment service of a fulfillment order.
Sends a fulfillment request to the fulfillment service of a fulfillment order.