Managing fulfillments with the Fulfillment and FulfillmentService resources
This guide explains how to use the Fulfillment and FulfillmentService resources to create and complete fulfillments. You can use these resources either separately or in tandem, depending on your use case.
Before you create fulfillments, it's helpful to understand some of the different fulfillment-related resources:
- Order: Contains information about an order, including an array of the line items that were purchased. Line items contain important fulfillment information, such as the associated variant, the quantity purchased, and the fulfillment status.
- Location: Represents a geographical location where a line item can be fulfilled from. A fulfillment service always has its own location, and variants managed by the fulfillment service should always be fulfilled from that location.
- Fulfillment: Represents a shipment of one or more items in an order. It includes the line item that the fulfillment applies to, its tracking information, and the location of the fulfillment.
- FulfillmentService: Represents a third-party warehousing service that prepares and ships orders on behalf of the store owner. Each fulfillment service is associated with its own location. When you create a fulfillment service, a new location is automatically created and associated with it.
Each order includes a list of line items that need to be fulfilled. Each line item has a fulfillment service field that specifies how the item is fulfilled, depending on how the inventory is managed:
- If a line item's inventory is managed manually at a merchant-created location, then the line item can be fulfilled by using either the Fulfillment resource (REST) or the createFulfillment mutation (GraphQL). You need to determine the location where the item will be fulfilled from, and then create a fulfillment that includes the location's ID.
- If a line item's inventory is managed by a fulfillment service, then Shopify creates a fulfillment automatically. The fulfillment service needs to complete the fulfillment after the item has shipped. Fulfillment service apps should subscribe to the
fulfillment/createwebhook to be notified of any new fulfillment requests.
Create a fulfillment
The following steps walk through the process of identifying a line item in an order that needs to be fulfilled and then creating a fulfillment.
- Step 1: Query the order to see its line items
- Step 2: Query the variant for its inventory item
- Step 3: Get the inventory levels
- Step 4: Create the fulfillment
Step 1: Query the order to see its line items
To get started, retrieve the line items of the order that you want to create a fulfillment for.
Step 2: Query the variant for its inventory item
After you've queried the order's line items, you can use variant IDs to find the specific variants that are associated with the inventory item that you want to fulfill.
If an order contains line items without product or variant IDs, then those items can be fulfilled using any of the shop's locations.
Step 3: Get the inventory levels
Now that you have the inventory item ID, you can find the inventory level for that item and the location where it's stocked.
The response shows that the variant is stocked at three different locations. The next step shows how to create a fulfillment from the
Step 4: Create the fulfillment
After you determine where the item is currently stocked and which stocked location you want to fulfill it from, you can create the fulfillment.
The FulfillmentService resource
A fulfillment service is a third-party warehouse that prepares and ships orders on behalf of a merchant. Fulfillment services can update product inventory levels, complete fulfillments, and provide shipment tracking information.
Registering as a fulfillment service
To register as a shop's fulfillment service on Shopify, use the FulfillmentService resource.
Fulfillment service locations
When you create a fulfillment service, a location is automatically associated with that fulfillment service. The ID of that location is included in the response when you create the fulfillment service. You can also retrieve the location ID by using the FulfillmentService resource.
The location ID identifies the location that's connected to this fulfillment service. You need to provide the location ID when creating fulfillments and adjusting inventory levels.
Set products to be fulfilled by your fulfillment service
A fulfillment service is associated with a product variant to show that the variant is fulfilled and shipped by that particular fulfillment service.
If you want your fulfillment service to manage inventory exclusively for an item and prevent merchants from overriding inventory levels, then set the
fulfillment_service field on the product variant to the handle of your fulfillment service. Also make sure that the SKU of the product variant matches that of the item at your fulfillment service.
If you want your fulfillment service to manage inventory exclusively for an item and prevent merchants from overriding inventory levels, then use the ID of your fulfillment service as the value for
fulfillmentServiceID. Also make sure that the SKU of the product variant matches that of the item at your fulfillment service.
Complete a pending fulfillment
If an order is placed and contains a line item that has
fulfillment_service set to your fulfillment service, then Shopify automatically creates a fulfillment and sets the
fulfillment_status to "pending" until your fulfillment service completes it.
Complete the fulfillment
To complete a fulfillment, send a POST request to the
If the fulfillment isn't initiated from the Shopify admin, then your fulfillment service will need to create the fulfillment.
Syncing fulfillment service inventory levels with Shopify
Fulfillment services can keep a merchant's inventory up to date in Shopify in two ways:
- Use the inventory resources to update inventory manually.
- Expose a
fetch_stockendpoint that returns inventory levels to sync inventory automatically.
Update inventory using the inventory resources
See the following resources for information on how to update inventory levels using the inventory resources:
If a variant's inventory is managed by your fulfillment service, then you can provide a
fetch_stock endpoint that returns your available quantities. The endpoint should expect a
shop URL parameter and an optional
sku parameter. Shopify uses this endpoint in two ways:
- Checking inventory levels for an individual SKU when a product is created or updated.
- Checking inventory for all products managed by the fulfillment service (once per hour).
See the following resources for more information on Shopify's
Example: Getting inventory level for a single variant
This example requests the inventory of a single product. The request includes the variant's SKU and the shop's URL. The response contains the variant's SKU and inventory quantity.
Example: Getting inventory levels for all variants
This example requests the inventory of all variants fulfilled by a fulfillment service. The response includes each variant's SKU and inventory quantity.
See these additional resources for more information about migrating your apps to support fulfillments across multiple locations:
- Migrating to multi-location inventory
- Fulfillment resource
- FulfillmentService resource
- Shopify API Forums
For API feature requests, bug reports, and other questions related to multi-location fulfillment, contact Shopify from your Partner Dashboard.