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.

{
  "order": {
    "id": 484460920854,
    "email": "plzfulfill@shopi.com",
    "admin_graphql_api_id": "gid://shopify/Order/484460920854",
    "line_items": [
      {
        "id": 1237517205526,
        "variant_id": 12195009364024,
        "title": "Blue Silk Tuxedo",
        "quantity": 1,
        "fulfillment_service": "manual",
        "product_id": 1321541042232,
        "fulfillable_quantity": 1,
        "fulfillment_status": null,
        "admin_graphql_api_id": "gid://shopify/LineItem/1237517205526",
      }
    ],
    "fulfillments": [],
  }
}

{
  "id": "gid://shopify/Order/484460920854"
}

query getOrderByID($id: ID!) {
  order(id: $id) {
    id
    name
    lineItems (first:20) {
      edges {
        node {
          id
          fulfillmentStatus
          variant {
            id
          }
        }
      }
    }
  }
}

  {
    "order": {
      "id": "gid://shopify/Order/484460920854",
      "name": "#1810",
      "lineItems": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/LineItem/1237517205526",
              "fulfillmentStatus": "unfulfilled",
              "variant": {
                "id": "gid://shopify/ProductVariant/12195009364024"
              }
            }
          }
        ]
      }
    }
  }

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.

{
  "id": 12195009364024,
  "product_id": 1321541042232,
  "title": "xs",
  "inventory_item_id": 12250274365496,
  "admin_graphql_api_id": "gid://shopify/ProductVariant/12195009364024"
}

{
  "id":"gid://shopify/ProductVariant/12195009364024"
}

query getVariantByID($id: ID!) {
  productVariant(id: $id) {
    id
    title
    inventoryItem {
      id
    }
  }
}

    {
      "productVariant": {
        "id": "gid://shopify/ProductVariant/12195009364024",
        "title": "xs",
        "inventoryItem": {
          "id": "gid://shopify/InventoryItem/12250274365496"
        }
      }
    }

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.

{
  "inventory_levels": [
    {
      "inventory_item_id": 12250274365496,
      "location_id": 6884556842,
      "available": 8,
      "updated_at": "2018-06-18T11:49:50-04:00",
      "admin_graphql_api_id": "gid://shopify/InventoryLevel/6485147690?inventory_item_id=12250274365496"
    },
    {
      "inventory_item_id": 12250274365496,
      "location_id": 13968834616,
      "available": 50,
      "updated_at": "2018-06-26T14:44:30-04:00",
      "admin_graphql_api_id": "gid://shopify/InventoryLevel/13570506808?inventory_item_id=12250274365496"
    },
    {
      "inventory_item_id": 12250274365496,
      "location_id": 13968867384,
      "available": 100,
      "updated_at": "2018-06-26T14:44:30-04:00",
      "admin_graphql_api_id": "gid://shopify/InventoryLevel/13570539576?inventory_item_id=12250274365496"
    }
  ]
}

{
  "id": "gid://shopify/InventoryItem/12250274365496"
}

query getInventoryItemByID($id: ID!) {
  inventoryItem(id: $id) {
    id
    inventoryLevels (first:6) {
      edges {
        node {
          id
          available
          location {
            id
          }
        }
      }
    }
  }
}

{
    "inventoryItem": {
      "id": "gid://shopify/InventoryItem/12250274365496",
      "inventoryLevels": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/InventoryLevel/6485147690?inventory_item_id=12250274365496",
              "available": 8,
              "location": {
                "id": "gid://shopify/Location/6884556842"
              }
            }
          },
          {
            "node": {
              "id": "gid://shopify/InventoryLevel/13570506808?inventory_item_id=12250274365496",
              "available": 50,
              "location": {
                "id": "gid://shopify/Location/13968834616"
              }
            }
          },
          {
            "node": {
              "id": "gid://shopify/InventoryLevel/13570539576?inventory_item_id=12250274365496",
              "available": 100,
              "location": {
                "id": "gid://shopify/Location/13968867384"
              }
            }
          }
        ]
      }
    }
  }

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.

{
  "fulfillment": {
    "location_id": "{location_rest_id}",
    "tracking_number": "{tracking_number}",
    "line_items": [
      {
        "id": "{line_item_rest_id}"
      }
    ]
  }
}

{
  "fulfillment": {
    "id": 392824225814,
    "order_id": 484460920854,
    "name": "#1810.1",
    "admin_graphql_api_id": "gid://shopify/Fulfillment/392824225814",
    "line_items": [
      {
        "id": 1237517205526,
        "variant_id": 12195009364024,
        "fulfillment_service": "manual",
        "product_id": 1321541042232,
        "variant_inventory_management": "shopify",
        "fulfillment_status": "fulfilled",
        "admin_graphql_api_id": "gid://shopify/LineItem/1237517205526",
      }
    ]
  }
}

{
  "input": {
    "orderId": "gid://shopify/Order/484460920854",
    "lineItems": {
      "id": "gid://shopify/LineItem/1237517205526",
      "quantity": 1
    },
    "location_id": "gid://shopify/Location/6884556842"
  }
}

mutation createFulfillment($input: FulfillmentInput!) {
  fulfillmentCreate(input: $input) {
    fulfillment {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

  {
    "fulfillmentCreate": {
      "fulfillment": {
        "id": "gid://shopify/Fulfillment/392860106774",
        "status": "SUCCESS"
      },
      "userErrors": []
    }
}

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": {
    "name": "TutorialFulfillment",
    "callback_url": "http://google.com",
    "inventory_management": true,
    "tracking_support": true,
    "requires_shipping_method": true,
    "format": "json"
  }
}

{
  "fulfillment_service": {
    "id": 386007062,
    "name": "TutorialFulfillment",
    "handle": "tutorialfulfillment",
    "email": null,
    "include_pending_stock": false,
    "requires_shipping_method": true,
    "service_name": "TutorialFulfillment",
    "inventory_management": true,
    "tracking_support": true,
    "provider_id": null,
    "location_id": 14027849750
  }
}

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.

{
  "fulfillment_services": [
    {
      "id": 386007062,
      "name": "TutorialFulfillment",
      "handle": "tutorialfulfillment",
      "email": null,
      "include_pending_stock": false,
      "requires_shipping_method": true,
      "service_name": "TutorialFulfillment",
      "inventory_management": true,
      "tracking_support": true,
      "provider_id": null,
      "location_id": 14027849750
    }
  ]
}

query getFulfillmentServices {
  shop {
    fulfillmentServices  {
      id
      handle
      location {
        id
        name
      }
    }
  }
}

{
  "shop": {
    "fulfillmentServices": [
      {
        "id": "gid://shopify/FulfillmentService/manual",
        "handle": "manual",
        "location": {
          "id": "gid://shopify/Location/6884556842",
          "name": "150 Elgin"
        }
      },
      {
        "id": "gid://shopify/FulfillmentService/386007062?id=true",
        "handle": "tutorialfulfillment",
        "location": {
          "id": "gid://shopify/Location/14027849750",
          "name": "TutorialFulfillment"
        }
      }
    ]
  }
}

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.

{
  "variant": {
    "id": 808950810,
    "fulfillment_service": "oberlo",
    "sku": "ABC-123"
  }
}

{
  "input": {
    "id": "gid://shopify/ProductVariant/12221024698390",
    "fulfillmentServiceId": "gid://shopify/FulfillmentService/386007062?id=true",
    "inventoryManagement": "FULFILLMENT_SERVICE"
  }
}

mutation assignVariantToFulfillmentService($input: ProductVariantInput!) {
  productVariantUpdate(input: $input) {
    productVariant {
      id
      fulfillmentService {
        id
        handle
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "productVariantUpdate": {
    "productVariant": {
      "id": "gid://shopify/ProductVariant/12221024698390",
      "fulfillmentService": {
        "id": "gid://shopify/FulfillmentService/386007062?id=true",
        "handle": "tutorialfulfillment"
      }
    },
    "userErrors": []
  }
}

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:

• Updating inventory
• Common use cases

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:

• The callback_url property
• Example fetch_stock call

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.