What To Settle Before You Build A Shopify App

What Should You Design First In A Shopify App?

If you are building for the App Store, design for the compliance webhooks, the OAuth order and the billing behaviour before you write the feature.

All three are stated requirements rather than preferences, and the compliance webhooks come with an explicit consequence attached. Shopify's wording is that if you do not provide URLs for the mandatory compliance webhooks, or your app does not respond to them as required, then your app will be rejected and you will need to fix the identified problem before submitting for another review.

That is an explicit gate with an explicit consequence, which is why I would settle it at the start of a build rather than at the end.

The Three Compliance Webhooks

Named exactly, because the names are the requirement.

1. customers/data_request, for requests to view stored customer data.
2. customers/redact, for requests to delete customer data.
3. shop/redact, for requests to delete shop data.

Each carries stated handling requirements. The app must respond with a 200 series status code. It must complete the action within 30 days of receiving the request, with exceptions where data retention is legally required. The requests arrive as POST with a JSON body and Content-Type: application/json. And an invalid Shopify HMAC header must be answered with 401 Unauthorized.

Two things about that list are worth pausing on.

The 30 day window is an obligation about the action, not about the response. Returning a 200 is not the same as having done the thing, and the documentation separates them.

And the HMAC requirement is a security check with a specific failure code. Answering an unsigned request with anything other than a 401 is a defect even if nothing else goes wrong.

The Exception Worth Reading Carefully

One clause in the compliance webhook requirements does more work than its length suggests.

The obligation is to complete the action within 30 days of receiving the request, with exceptions where you are legally required to retain the data.

Shopify states the exception and no more than that. My own reading, which it does not say, is that relying on it in practice means being able to name which data you are retaining and on what legal basis, because otherwise there is nothing to distinguish it from simply not deleting.

My own reading is that this belongs in the same schema conversation as shop/redact rather than in a legal review at the end. If some records must be kept for a statutory retention period and others must go, the app has to be able to tell them apart on request. A schema that cannot separate them turns a narrow exception into a blanket one, which is not what the requirement says.

The practical version is a short list: what you store, how long the law requires you to keep each of those things, and what happens to the rest inside 30 days. Written down before the schema is fixed, that is an afternoon. Written down afterwards it is a migration.

OAuth Has An Order

Shopify's requirement is that your app should immediately authorise using OAuth before any other steps occur, even if the merchant has previously installed and then uninstalled your app.

The clause about reinstallation is the one that catches builds. An app that remembers a previous install and skips straight to its own interface is doing something the requirement rules out. In my experience that shortcut usually arrives as a convenience during development and survives into review.

The practical version is to treat OAuth as the entry point with no branches around it, rather than as a step that can be skipped when the app recognises a shop.

Billing Has To Be Self Service

Shopify's requirement is that your app should allow merchants to upgrade and downgrade their pricing plan without having to contact your support team or having to reinstall the app.

Both halves matter. My own reading of the second is that it is really a constraint on where plan state lives: if changing plan means reinstalling, plan and install are bound together somewhere, and separating them later is more than a feature change. Shopify states the requirement rather than that consequence.

My own view is that this is the requirement most worth reading before the pricing model is agreed, because a pricing model with plans that cannot be moved between is a commercial decision that quietly becomes an engineering problem.

Performance Has A Number

This one is short and specific. Shopify's requirement is that your app should not reduce Lighthouse performance scores by more than 10 points.

That is a budget, and like any budget it is easier to hold if you know it exists at the start. It also connects to the merchant side of the same problem, which I have written about separately in What Is Actually Worth Optimising On A Shopify Store: apps loading assets on the storefront are named by Shopify as a performance factor merchants can control.

Shopify's merchant guidance separately names too many apps loading assets on the storefront as something that can slow performance. My own reading is that designing to load only where the feature is used serves both the app requirement and the merchant's side of it.

What Review Asks For

Worth knowing before submission rather than during it. Shopify asks you to provide clear instructions and a complete screencast showing your app's setup process and functionality, and states that if your app integrates with third party platforms you should include valid test credentials that grant full access.

The test credentials clause is the one I would plan for. An app that integrates with a third party system needs a working account on that system, with enough access to demonstrate the whole flow, available at review time. That is an arrangement to make early rather than a file to attach late.

Example: An Order Sync App That Leaves Compliance Late

This is a constructed example, not a client engagement. It is assembled from the requirements above.

A team is building a public app that syncs orders into an external accounting system. The feature work is understood. The plan is to handle compliance and billing near the end.

Reading the requirements first changes the shape of the build in four places.

The compliance webhooks need somewhere to answer from on day one, and shop/redact in particular has to know what the app stored for that shop, which is a question about the data model rather than about an endpoint. Deciding it late means retrofitting deletion into a schema that was not designed for it.

OAuth becomes the single entry point, with no reinstall shortcut, which affects how sessions are stored.

Plan changes have to work without reinstalling, so the plan cannot be an attribute of the install record.

And the accounting integration means review will want working test credentials for that accounting system, so somebody has to own a demonstration account before submission.

None of those four is difficult in itself. All four are cheaper before the feature exists than after, which is my argument for reading the requirements as an architecture document rather than as a submission checklist.

Signs Your Shopify App Is Being Built In The Wrong Order

Five signals.

1. Your build plan has compliance webhooks in a phase after the feature work.
2. Nobody can say what shop/redact would have to delete in your schema.
3. Your app skips OAuth when it recognises a shop it has seen before.
4. Changing plan in your pricing model would mean reinstalling.
5. You integrate with a third party system and nobody owns a test account for review.

Signal two is the one I would check first, because it is a data model question wearing an endpoint's clothing, and data model questions get more expensive with every week of build.

If any apply, you can Request The Free Shopify Store Audit. The main site has a Shopify Section.

Common Questions About Shopify Apps

What Are The Mandatory Shopify Compliance Webhooks?

Three, for apps submitted to the App Store: customers/data_request for requests to view stored customer data, customers/redact for requests to delete customer data, and shop/redact for requests to delete shop data. Each must return a 200 series status code and the action must be completed within 30 days of the request.

What Happens If An App Does Not Handle Compliance Webhooks?

Shopify states that if you do not provide URLs for the mandatory compliance webhooks, or your app does not respond to these webhooks as required, then your app will be rejected and you will need to fix the identified problem before submitting your app for another review.

When Should A Shopify App Authorise With OAuth?

Shopify's requirement is that the app should immediately authorise using OAuth before any other steps occur, even if the merchant has previously installed and then uninstalled the app. The reinstallation clause rules out skipping authorisation for a shop the app has seen before.

Do Shopify Apps Have A Performance Limit?

Yes, for apps submitted to the App Store. Shopify's requirement is that an app should not reduce Lighthouse performance scores by more than 10 points. Shopify separately tells merchants that too many apps loading assets on the storefront can slow performance.

What Does Shopify App Review Ask For?

Clear instructions and a complete screencast showing the app's setup process and functionality. Shopify also states that if your app integrates with third party platforms you should include valid test credentials that grant full access, which means arranging a demonstration account before submission.

Part of The Shopify Development Guide. See also What Belongs In A Shopify Function, What Already Broke In Checkout and Migration And Replatforming.