Migrating to multi-location inventory

Important

After July 1, 2018, apps will no longer be able to use the ProductVariant API to adjust inventory. Additionally, fulfillments and refunds with restocks will require a location_id at creation.

As Shopify moves towards expanding its multi-location inventory capabilities, it is important that your apps are updated so they can continue to work on stores that track inventory across multiple locations.

Inventory is currently set and adjusted on the product variant and is not tracked by any specific location. In anticipation of multi-location inventory being available in the Shopify admin, Shopify is releasing a new Inventory API, which includes three resources: InventoryItem, InventoryLevel, and Location. The Inventory API allows apps to retrieve, set, and update Shopify store inventory levels across multiple locations. Additionally, it allows apps to specify the location where they are fulfilling orders or restocking items.

Determining whether your app will be affected by multi-location inventory

Your app is at risk of being affected by multi-location inventory if it performs any of the following deprecated actions:

  • setting inventory_quantity on the product variant via the Product API or Product Variant API
  • updating inventory using inventory_quantity_adjustment on the product variant via the Product Variant API
  • fulfilling orders without specifying a location using location_id, see the Fulfillment Migration Guide for more details
  • issuing refunds and restocking items without specifying a location using location_id

Affected APIs

The following table describes the new behaviour of APIs affected by multi-location inventory:

Affected API Changing behaviour
Product API / Product Variant API
  • inventory_quantity on a Product Variant object will return the total available quantity of inventory across all locations.
  • Updating SKU will only be available using the Inventory Item endpoint.
  • There is a new 1:1 relationship between Product Variant and Inventory Item. Each product variant includes a inventory_item_id.

The following behaviors are temporary and exist only to help you migrate to the Inventory API. Updating inventory using the Product and ProductVariant APIs is deprecated, and should no longer be relied upon to update inventory.

  • Setting inventory_quantity_adjustment will adjust a product variant's inventory at its location that has the lowest ID. Use the Inventory Level endpoint instead.
  • Setting inventory_quantity will adjust a product variant's inventory at its location that has the lowest ID. The inventory at that location will be adjusted so that the sum of inventory across all locations matches the value set by inventory_quantity. Use the Inventory Level endpoint instead.

Example scenario:
Ottawa location (ID: 101) has 2 blue hats.
Toronto location (ID: 102) has 10 blue hats.
Montreal location (ID: 103) has 6 blue hats.

Example 1:
Setting inventory_quantity_adjustment: 4 on the product variant adjusts its inventory at the Ottawa location by +4 because that location has the lowest ID.

Example 2:
Setting inventory_quantity: 30 on the product variant adjusts its inventory at the Ottawa location by +12 because that location has the lowest ID. The sum of inventory across all locations now equals 30.

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 managed by that fulfillment service location.

Location API
  • Inventory levels can now be accessed via the 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.
Inventory Item API
  • An Inventory Item represents the physical good available to be shipped to a customer. It holds essential information about the physical good, including its SKU and whether inventory is tracked.
  • There is a 1:1 relationship between Product Variant and Inventory Item.
Inventory Level API
  • An Inventory Level represents the quantity of an inventory item at a specific location.
Fulfillment API
  • Every fulfillment will include a new location_id property, 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.

See the Fulfillment Migration Guide for more details.

Refund API

Note

This feature is not yet available.

  • To create a new refund and restock the item, an app must specify the location where they want to restock the item.
Shop API
  • The Shop object now includes the multi_location_enabled property, which returns whether a shop is tracking inventory across multiple locations.

Note

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

Deprecation schedule

February 12, 2018
  • The Inventory API is available to all partners.
March 1, 2018
  • Deprecation begins for setting inventory_quantity and inventory_quantity_adjustment.
  • Apps can specify location_id when creating fulfillments
May 14, 2018
  • All public apps created before this date that previously had the read_products and write_products permissions will automatically be granted the read_inventory and write_inventory permissions until September 1, 2018.
July 1, 2018
  • Apps will no longer be able to set inventory_quantity or inventory_quantity_adjustment on the product variant.
  • Apps will no longer be able to create fulfillments without specifying a location_id.
  • Apps will no longer be able to refund and restock without specifying a location_id.

Inventory permissions and authentication

To use the new Inventory API, your app must request either the read_inventory or write_inventory permission during the Ask for permission step of OAuth.

This step includes displaying a prompt by redirecting the user to this URL:

https://{shop}.myshopify.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]={option}

where {scopes} would include either read_inventory or write_inventory. Once accepted, your app can make authenticated requests to the Inventory API.

It is possible for Shopify to automatically grant your existing users with the new permissions. To request this, please contact deprecations@shopify.com.

Rate limiting

It's not currently possible to update multiple inventory levels in a single API request using the Inventory API. If you run into API request limits as a result of this change, then contact deprecations@shopify.com with your use case.

Inventory webhooks

To stay in sync with inventory changes across multiple locations, you can subscribe to the following webhook events:

Inventory levels Inventory items Locations
inventory_levels/create inventory_items/create locations/create
inventory_levels/update inventory_items/update locations/create
inventory_levels/delete inventory_items/delete locations/delete

Common use cases

Use the following list of common scenarios to help you find the related reference docs.

Checking inventory levels

Apps can regularly check inventory levels of inventory items at various locations.

Use these endpoints

GET /admin/inventory_levels.json for retrieving a list of inventory levels.
GET /admin/locations/#{location_id}/inventory_levels.json for retrieving a list of inventory levels of all items at a particular location.

Updating inventory

Apps can update inventory levels for a specific item at any location.

Use these endpoints

POST /admin/inventory_levels/adjust.json for adjusting inventory levels of a particular inventory item within a location.
POST /admin/inventory_levels/set.json for setting the total available quantity of inventory for a single inventory item within a location.

Fulfilling orders

Apps can specify exactly at which location to fulfill an order.

Use these endpoints

POST /admin/fulfillments.json for creating a fulfillment at a specific location.
POST /admin/fulfillmentservices.json for creating a fulfillment service. See the Fulfillment Migration Guide for more details.

Managing locations

Apps can retrieve a list of all shop locations or create a new location using a fulfillment service.

Use these endpoints

GET /admin/locations.json for retrieving all locations associated to a shop.
POST /admin/fulfillmentservics.json for creating a legacy location. Read our Fulfillment Migration Guide to understand how fulfillment services works with multi-location.

Migration checklist

Use the following checklist to make sure that your apps support multi-location inventory:

Additional resources

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

Getting support

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