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.
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 assignmentStatus 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 read_assigned_fulfillment_orders 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.
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.
Fulfillment orders are governed by the following API access scopes:
The read_merchant_managed_fulfillment_orders and
write_merchant_managed_fulfillment_orders access scopes
grant access to fulfillment orders assigned to merchant-managed locations.
The read_assigned_fulfillment_orders and write_assigned_fulfillment_orders
access scopes are intended for fulfillment services.
These scopes grant access to fulfillment orders assigned to locations that are being managed
by fulfillment services.
The read_third_party_fulfillment_orders and write_third_party_fulfillment_orders
access scopes grant access to fulfillment orders
assigned to locations managed by other fulfillment services.
Fulfillment service app access scopes
Usually, fulfillment services have the write_assigned_fulfillment_orders access scope
and don't have the *_third_party_fulfillment_orders
or *_merchant_managed_fulfillment_orders 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 write_merchant_managed_fulfillment_orders and
write_third_party_fulfillment_orders 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.
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).
channelId•
ID
ID of the channel that created the order.
createdAt•
DateTime!
non-null
Date and time when the fulfillment order was created.
deliveryMethod•
DeliveryMethod
Delivery method of this fulfillment order.
destination•
FulfillmentOrderDestination
The destination where the items should be sent.
fulfillAt•
DateTime
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 fulfill_at date for a subscription order might be the 1st of each month, a pre-order fulfill_at date would be nil, and a standard order fulfill_at date would be the order creation date.
fulfillBy•
DateTime
The latest date and time by which all items in the fulfillment order need to be fulfilled.
fulfillmentHolds•
[FulfillmentHold!]!
non-null
The fulfillment holds applied on the fulfillment order.
fulfillmentOrdersForMerge•
FulfillmentOrderConnection!
non-null
Fulfillment orders eligible for merging with the given fulfillment order.
fulfillments•
FulfillmentConnection!
non-null
A list of fulfillments for the fulfillment order.
id•
ID!
non-null
A globally-unique ID.
internationalDuties•
FulfillmentOrderInternationalDuties
The duties delivery method of this fulfillment order.
lineItems•
FulfillmentOrderLineItemConnection!
non-null
A list of the fulfillment order's line items.
locationsForMove•
FulfillmentOrderLocationForMoveConnection!
non-null
A list of locations that the fulfillment order can potentially move to.
merchantRequests•
FulfillmentOrderMerchantRequestConnection!
non-null
A list of requests sent by the merchant or an order management app to the fulfillment service for the fulfillment order.
order•
Order!
non-null
The order that's associated with the fulfillment order.
orderId•
ID!
non-null
ID of the order that's associated with the fulfillment order.
orderName•
String!
non-null
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.
orderProcessedAt•
DateTime!
non-null
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.
requestStatus•
FulfillmentOrderRequestStatus!
non-null
The request status of the fulfillment order.
status•
FulfillmentOrderStatus!
non-null
The status of the fulfillment order.
supportedActions•
[FulfillmentOrderSupportedAction!]!
non-null
The actions that can be performed on this fulfillment order.
updatedAt•
DateTime!
non-null
The date and time when the fulfillment order was last updated.
