Migrating to multi-location fulfillment

Location required when creating fulfillments

By July 1st, 2018, apps must provide a location_id when creating fulfillments.

As Shopify moves towards expanding its multi-location inventory capabilities, fulfillment apps will need to specify the location from which they are fulfilling orders to continue to work on stores that track inventory across multiple locations.

For a complete list of all APIs affected by the release of multi-location inventory, see Affected APIs.

Affected API Changing behaviour
Fulfillment API
  • Every fulfillment will include a new property, location_id, which is the unique identifier of the location tied to the fulfillment.
  • When creating a fulfillment, an app must specify the location from which an item is fulfilled using location_id.
FulfillmentService API
  • When an app registers a new FulfillmentService on a store, Shopify automatically creates a Location that's associated with that FulfillmentService.
  • There is a new location_id property on the FulfillmentService object that is the unique identifier of the location that's tied to the fulfillment service.
  • All product variant's assigned to a fulfillment service have their inventory quantities stored in the fulfillment service location.

Important

If a variant is associated with a fulfillment service, then its inventory can only be tracked by that fulfillment service location.

Location API
  • There is a legacy property on the Location object. If true, then the location is a fulfillment service location. If false, then the location was created by the merchant and isn't tied specifically to a fulfillment service.
Shop API
  • The Shop object now includes the multi_location_enabled property, which returns true when a shop is tracking inventory across multiple locations.

Note

Use shop/update webhooks to determine when a shop enables multi-location.

Sample multi-location fulfillment API requests

When creating a fulfillment, you will need to specify a location_id indicating the location from which you're fulfilling the order. If you want to fulfill line items at different locations, then create a separate fulfillment for each line item belonging to a different location.

POST /admin/orders/#{order_id}/fulfillments.json

{
  "fulfillment": {
    "tracking_number": null,
    "location_id": 123,
    "line_items": [
      {
        "id": 466157049
      }
    ]
  }
}

Using the FulfillmentService API to manage inventory and fulfillments

A fulfillment service is a third party warehouse that prepares and ships orders on behalf of the merchant. Fulfillment services can also update product inventory levels, create fulfillments, and provide shipment tracking information. Many dropshippers on Shopify identify as fulfillment services.

Registering as a fulfillment service

To register as a fulfillment service on Shopify, use the FulfillmentService resource.

POST /admin/fulfillment_services.json

{
  "fulfillment_service": {
    "name": "Oberlo",
    "callback_url": "https://oberlo.com",
    "inventory_management": true
  }
}

Learn more about registering a fulfillment service in the FulfilmentService API reference.

Fulfillment service locations

When you create a fulfillment service, Shopify creates a location tied to that fulfillment service. The ID of the location can be retrieved from the response body of the fulfillment service create request or through the FulfillmentService API:

GET /admin/fulfillment_services.json

{
  "fulfillment_services": [
    {
      "id": 755357713,
      "name": "Oberlo",
      "handle": "oberlo",
      "service_name": "Oberlo App",
      "inventory_management": true,
      "tracking_support": true,
      "location_id": 48752903
    }
  ]
}

The location_id field identifies the location that's connected to this fulfillment service. You will need this location_id when creating fulfillments or adjusting inventory levels.

It’s important to understand the differences of a fulfillment service location and a location created from within the admin. To read more about the different location types, see Inventory levels and fulfillment service locations.

Set products to be fulfilled by your fulfillment service

A fulfillment service is set on the product variant to indicate that it is intended to be fulfilled and shipped by that particular fulfillment service. Use the handle of your fulfillment service as the value for fulfillment_service and ensure that the SKU of your product variant matches that of the item at your fulfillment service.

PUT /admin/variants/#{variant_id}.json

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

Important

Variants assigned to fulfillment services are not currently eligible to be stocked in multiple locations.

Managing inventory as a fulfillment service

If you want to expose inventory quantities to merchants, then you could do so in a few different ways.

Using callback URLS

Shopify will make a request to your fulfillment service for inventory levels of an individual SKU when the product is set up initially or is changed in the Shopify admin. A request for all inventory data will happen once every hour to keep our system up to date with your fulfillment service. This is currently the only available way to bulk update inventory levels using the Shopify REST API.

Note

Shopify requests to your callback URLs will fail if the SKU of the product variant does not match that of the item at your fulfillment service.

Get inventory level for a particular SKU

GET https://oberlo.com/fetch_stock.json?sku=123&shop=testshop.myshopify.com

Sample response: {"123": 1000}

Get inventory levels for all SKUs

GET https://oberlo.com/fetch_stock.json?shop=testshop.myshopify.com

Sample response: {"123": 1000, "456": 500}

If you want your fulfillment service to manage all inventory for an item and prevent merchants from overriding inventory levels, then make sure to set the inventory_management field on the product variant to the handle of your fulfillment service.

PUT /admin/variants/#{variant_id}.json

{
  "variant": {
    "id": 808950810,
    "inventory_management": "oberlo"
  }
}

Using the Inventory API

See Migrating to multi-location inventory for more information.

Fulfilling orders using a fulfillment service

It is recommended that your app subscribe to the fulfillment/create webhook to be notified of any new fulfillments. This webhook fires when the merchant begins the fulfillment process.

Every line item in a Shopify order has an associated fulfillment service under the field fulfillment_service. Check this field to determine if your service should be fulfilling the line item.

If the merchant begins the fulfillment process and an order line item uses your fulfillment service, then the fulfillment will be automatically created and the status will be set to pending until your fulfillment service has completed the fulfillment.

To complete a fulfillment, send a POST request to the complete endpoint. You can also update the fulfillment via the API with other information like tracking numbers, rather than waiting for Shopify to ask for them.

POST /admin/orders/#{order_id}/fulfillments/#{fulfillment_id}/complete.json

Note

A fulfillment doesn’t have to transition from pending to complete. It can transition from pending to open or be cancelled altogether. See the Fulfillment resource for more information.

If the fulfillment isn’t initiated from the Shopify admin, your fulfillment service will need to create the fulfillment.

POST /admin/orders/#{order_id}/fulfillments.json

{
  "fulfillment": {
    "location_id": 48752903,
    "tracking_number": "123456789010",
    "tracking_company": "fed ex",
    "line_items": [
      {
        "id": 466157049
      }
    ]
  }
}

Important

You need to specify the location_id when creating fulfillments. This tells Shopify the location to associate with the fulfillment. Use the ID of your fulfillment service location.

Additional resources

Use these additional resources for more information about migrating your apps to support multi-location inventory:

Support

For API feature requests, bug reports, and other queries related to multi-location fulfillment, contact deprecations@shopify.com.