App integration with online stores

You can expose your app's features to millions of merchants' customers by integrating it with online stores.

The Shopify platform can match your app's needs, from something as small as a block of inline content, to augmentations that span the entire purchase experience. Our platform makes it possible to seamlessly incorporate your app's features into online stores using Liquid templates, hosted assets on the Shopify CDN, and a purpose-driven deployment and versioning release pipeline.

This guide explains the methods that you can use to integrate your app with online store themes.

Theme app extensions

Theme app extensions provide your app with two integration types that extend online store themes: app blocks and app embed blocks.

App blocks and app embed blocks are the recommended and most elegant way of integrating apps with online stores. These blocks are equipped to take full advantage of Online Store 2.0 features, like sections on all pages. They also prepare your app for the future when merchants increasingly adopt Online Store 2.0 themes that might not integrate as well with apps that use other methods.

Theme app extensions don't edit theme code, which provides the following benefits:

  • Reduced risk of an app introducing breaking changes to the theme

  • Minimized app support debt

  • Increased app adoption by offering merchants a cleaner experience for app integration and customization.

  • Increased user retention owing to a graceful, out of the box integration experience.

Review the following app use cases and the app block that you should use.

  • If your app injects inline content on a page, then use app blocks.

  • If your app doesn't have a UI component or if it adds a floating or overlaid element to a theme, then use app embed blocks.

Other methods

Shopify provides technical resources other than theme app extensions for integrating apps with online stores.

Review the following app use cases and the technical resource that you should use:

  • If your app injects app snippets into a theme's liquid code, then you can use the Asset REST Admin API resource.

  • If your app includes JavaScript code that's loaded onto a theme, then you can use the ScriptTag REST Admin API or GraphQL Admin API resource.

  • If your app fetches data from an outside location to display on a theme, then you can use app proxies.

Additional considerations

Using the Asset and ScriptTag resources means additional work to integrate your app with themes.

If your app interacts with a shop's theme, then you need to ensure that the app also works in the theme editor environment. If necessary, you can set your app to detect the theme editor so that you can adjust your app to work in that environment.

If your app adds a visible element to an online store, then the element should be deactivated by default so that the merchant can either preview or edit the element before activating it. You need to provide merchants who use the app with instructions on how to activate either the visible element or the app.

If uninstalling your app leaves code behind in the theme, then you need to provide merchants with instructions on how to remove the code completely, so that they can remain on their theme upgrade path. When a merchant removes the code, if they leave as much as an extra line break or space, then they'll be taken off their theme upgrade path.

If your app edits theme code and a merchant changes their published theme, then you need to update your app to work on the new theme.

JavaScript best practices

Because Shopify is a hosted solution, make sure that you're following our best practices for using JavaScript on a Shopify store.

Determine your app's integration method

Determine the method required to integrate an app with a theme by verifying whether a store's published theme supports app blocks. All themes support app embed blocks.