Manage fulfillments with 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.
Fulfillment resources
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.
Fulfillment behavior
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/create
webhook 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 6884556842
location.
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.
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 complete
endpoint.
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_stock
endpoint 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:
Expose the fetch_stock
endpoint
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 fetch_stock
calls:
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.
GET https://oberlo.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com
Sample Response
{
"123": 1000
}
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.
GET https://oberlo.com/fetch_stock.json?shop=testshop.myshopify.com
Sample Response
{
"123": 1000,
"456": 500
}
Additional resources
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
Support
For API feature requests, bug reports, and other questions related to multi-location fulfillment, contact Shopify from your Partner Dashboard.