Building an App

What an app can do, the App API, permissions, and installing into a shop.

An app is installed into a shop by its owner and runs with permissions that owner granted.

What an App Can Do

Add screens to the admin. Extend the checkout. Register script tags on the storefront. Subscribe to events. Read and write shop data within its permissions.

The App API

Separate from the merchant REST API, under /api/apps. Every endpoint, what it is for and how an installation authenticates is in The App API.

If you would rather see it built than described, Building an App, Step by Step goes from an empty directory to an installed app.

Permissions

An app declares what it needs and the merchant sees it at install.

Ask for the minimum. An app that wants customer data to reformat shipping labels will not be installed by anybody who reads the request, and the ones who do not read it are not the merchants you want.

One Shop Is Not All Shops

Every shop is a separate tenant with its own database. An install gives you access to that shop and nothing else.

If your app serves many merchants, you hold one set of credentials per shop and address each shop's own domain. There is no endpoint that spans them.

Uninstalling Cleanly

Remove your extensions, script tags and webhooks. Stop calling the shop.

Decide in advance what happens to data you created, and say so in your listing. A merchant who uninstalls and finds your data still on their products will say so publicly.

Billing

If you charge for your app, charges are raised against the installation rather than collected by you directly. Decide early whether you are charging a flat fee, per use, or not at all, because retrofitting billing into an app that merchants already installed for nothing is a conversation nobody enjoys.

Settings

An app can hold its own settings per installation, which is how a merchant configures it without leaving their admin. Keep them few and give each a sensible default, because an app that cannot work until somebody fills in six fields is an app that gets uninstalled during setup.

Handling Many Shops

Your service talks to every shop that installed it, and they are separate in every way that matters: separate databases, separate domains, separate tokens, separate data.

Hold one record per installation. Never cache something from one shop in a way another can read. And when you deploy, remember the change is live for every merchant at once with no staged rollout, so test against a shop with real volume rather than only your own.

Before You Publish

Install it on a shop with real data and use it for a week. Then uninstall it and check the shop is exactly as it was.

The second half is the part that gets skipped and the part that generates the complaints.