All Tutorials

Migrate your app to support multiple locations

All Tutorials

Migrate your app to support multiple locations

Migrate your app to support multiple locations

Shopify has launched Locations. This feature enables merchants to manage inventory, fulfillments, and restocks across multiple locations from the Shopify admin.

All apps that update, fulfill, or restock inventory need to be updated to work with stores using multiple locations. To update your app to use the new REST APIs, see the guides on Managing fulfillments and Updating inventory.

You can also migrate your app to manage inventory and fulfillments using GraphQL. For more information, see How the New GraphQL Admin API Can Help You Manage Inventory and Locations.

Deprecation schedule

February 12, 2018
  • The Inventory API is available to all partners and can be used on any shop in production regardless of Locations.
March 1, 2018
  • Deprecation begins for setting inventory_quantity and inventory_quantity_adjustment.
  • Apps can now specify location_id when creating fulfillments.
May 7, 2018
  • Shopify announces Locations. All partners now have the option to enable Locations on their development stores.
July 1, 2018
  • Public apps created after this date will no longer be able to do the following:
    • set inventory_quantity or inventory_quantity_adjustment on the product variant
    • create fulfillments without specifying a location_id
    • refund and restock without specifying a location_id
August 1, 2018
  • Shops are able to add multiple locations where they can track inventory. Apps might become incompatible with shops with more than one location if the app hasn't been migrated to support multiple locations.
January 6, 2019
  • Deprecation of legacy inventory calls is extended to all public apps. This means all public apps will no longer be able to do the following:
    • set inventory_quantity or inventory_quantity_adjustment on the product variant
    • create fulfillments without specifying a location_id
    • refund and restock without specifying a location_id
  • Shopify now requires read/write_inventory permissions for all apps using the Inventory API.
  • Grace period: Public apps can pass the bypas-multi-location-support: true header to continue using the following deprecated behaviour up until February 4, 2019.
February 4, 2019
  • The bypass-multi-location-support: trueheader will no longer allow deprecated behaviors.
October 1, 2019
  • Deprecation for legacy inventory calls is extended to all apps in 2019-10. This means that all apps, including private apps, that call this version or later will no longer be able to do the following:
    • set inventory_quantity or inventory_quantity_adjustment on the product variant
    • create fulfillments without specifying a location_id
    • refund and restock without specifying a location_id
July 1, 2020
  • The last version of the API that supported legacy inventory behavior, 2019-07, becomes unavailable.
  • The legacy inventory behavior is now fully deprecated.

Does my app support shops with multiple locations?

Your app is not compatible with multiple locations if it performs any of the following deprecated API actions:

  • Manages inventory with the Product and Product Variant resources
  • Fulfills orders without specifying a location to fulfill from
  • Issues refunds and restocks items without specifying a location to restock the items

How do I update my app to support multiple locations?

If you want your app to support shops with multiple locations, then you’ll need to change your app to use the following API actions instead:

  • Manage inventory with the Inventory API. For more information, see Updating inventory.
  • Fulfill orders from a location using location_id. For more information, see Managing fulfillments.
  • Issue refunds and restock items at a location using location_id and restock type.

What happens if I don’t update my app to support stores with multiple locations?

Any apps using deprecated APIs installed on a shop with more than one location are at high risk of causing inventory discrepancies for their users.

If Shopify detects that your app is using legacy API endpoints, Shopify will take the following action to prevent inventory issues caused by apps using deprecated APIs on shops with more than one location:

  • Shopify merchants with your app installed will be blocked from adding a new location. This can lead to merchants uninstalling your app, contacting your support teams, or leaving negative reviews for your app.

The warning message shown to merchants if they try to install your blocked app

  • Shopify merchants will be blocked from installing your app if they have more than 1 location:

The warning message shown to merchants if they try to install your blocked app

  • Private apps won't be able to perform deprecated API actions. If you have a private app that is incompatible with multiple locations, the shop owner will be able to add a new location, but your app will no longer be able to perform deprecated API actions, and may therefore stop working.

Shopify is removing deprecated APIs on January 6th, 2019. After the deprecated APIs are removed, merchants will be able to add locations with your app installed and they'll be able to install your app on any shop regardless of the number of locations they have. If you have not migrated to support the new APIs, then your app will break because the deprecated APIs will return errors.

How can I get help with my migration?

If you’re having issues updating your app, then contact Shopify from your Partner Dashboard.

You’ll need to specify what steps you're currently taking to support stores with multiple locations, and demonstrate that your app won’t cause inventory discrepancies for merchants who use multiple locations. Based on your submission, you might be asked to provide additional information.

Inventory permissions and authentication

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

During this step, you need to direct your merchants 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 your existing scopes as well as either read_inventory or write_inventory. After a merchant accepts, your app can make authenticated requests to the Inventory API.

Inventory webhooks

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

Inventory levels inventory_levels/connect, inventory_levels/update, inventory_levels/disconnect
Inventory items inventory_items/create, inventory_items/update, inventory_items/delete
Locations locations/create, locations/update, locations/delete

Migration checklist

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

Additional resources

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


Private Apps

All deprecated Inventory API actions have been removed. Your private apps will no longer be able to perform deprecated API actions, even if the target shop has a single location.

How do I update my app to support multiple locations?

If you want your app to support shops with multiple locations, then you’ll need to change your app to use the following API actions instead:

  • Manage inventory with the Inventory API. For more information, see Updating inventory.
  • Fulfill orders from a location using location_id. For more information, see Managing fulfillments.
  • Issue refunds and restock items at a location using location_id and restock type

Inventory webhooks

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

Inventory levels inventory_levels/connect, inventory_levels/update, inventory_levels/disconnect
Inventory items inventory_items/create, inventory_items/update, inventory_items/delete
Locations locations/create, locations/update, locations/delete

Migration checklist

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

Frequently Asked Questions

Can I update inventory levels in bulk?

Yes. You can use the GraphQL Admin API and the inventoryBulkAdjustQuantityAtLocation mutation to update inventory levels in bulk.

If you're using the REST Admin API and the adjust endpoint, then you can only update inventory levels individually.

Can I create new locations with the API?

No. The Location API is read-only.

How do I check if a shop uses multiple locations?

Query the Shop endpoint. If a shop is multi-location enabled, then the multi_location_enabled property returns true.

How many locations can a single Shopify store have?

The maximum number of locations that you can have depends on your plan:

  • Shopify Lite - 3
  • Basic Shopify - 4
  • Shopify - 5
  • Advanced Shopify - 8
  • Shopify Plus - 20 (Contact Plus Support if you need more than 20 locations.)

If a product variant is deleted, will its associated inventory item be automatically deleted as well?

Yes.

Why am I getting a 403 Forbidden error response code?

The server is refusing to respond to the request. This is usually because you haven't included the inventory scopes for this action. Make sure you have the required read/write_inventory permissions. For more information on the required permissions, see the guide for Migrating to multi-location inventory.

Additional resources

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