Shopify app onboarding best practices: install to first result

In short: A Shopify app's onboarding has one job: get the merchant from the install button to a real result from their own store, in the same session, with the fewest steps that make that possible. Shopify's own guidance says to authorize with OAuth before anything else, keep setup to five steps or fewer, and ask for information only when it is needed. Everything else, including most settings, can wait until the merchant has seen the app work.

Why does the first session decide whether a merchant keeps your app?

A merchant installs an app because something is broken or missing in their store today. They want to see whether your app fixes it. They do not want to learn your product. If the first session ends without a visible result, the install becomes one more icon in the Apps menu, and the next time they look at it is when they clean up their app list and their bill.

I spent close to two years in customer success at Social Snowball before I moved into product design, and I read the tickets a slow first session creates. The first session is not a tutorial. It is the trial.

Shopify's App Store best practices say it plainly: "Merchants should be able to quickly set up and start using your app." The rest of this guide is about what "quickly" looks like in practice.

The install-to-first-result path

I think of onboarding as five stages, and I design each one against a single question: does this stage move the merchant closer to seeing a result from their own store?

Stage	What happens	What it must not do
Install and OAuth	Merchant approves scopes and lands in your app	Add a signup form, a survey, or a pricing wall before the app loads
First screen	Merchant sees what the app will do with their store	Show an empty dashboard full of zeros
The one setup step	Merchant does the single action that makes the app work	Ask for anything that could be a default
First result	Merchant sees the app working on their real data	Show sample data when real data is available
Everything else	Settings, integrations, branding, advanced rules	Block the result behind any of it

What should happen during OAuth and the redirect?

The install step is mostly Shopify's, and that is a good thing. Shopify's best practices require that "your app should immediately authorize using OAuth before any other steps occur," and they say not to run OAuth in a pop-up window. If you built the app with Shopify's current template, managed installation handles scope approval and token exchange for you. Merchants approve the scopes once and you never write the OAuth flow yourself.

Two things are still yours to get right.

First, ask only for the scopes the first result needs. A scope list that covers customers, orders, products, themes, and discounts makes merchants hesitate, and a hesitation at the approve button is an install you never get. Shopify lets you add scopes later, and merchants approve the new ones the next time they open the app.

Second, make the redirect land somewhere useful. The merchant has just clicked approve, and the next screen is the first thing they see of your product. It should not be a login form, a "create your account" form, or a plan picker. They already have an account. It is their Shopify store. Use the shop domain as their identity and get them into the product.

What should the first screen show?

The first screen has to answer one question for the merchant: what is this app going to do with my store? Not what it can do in general. What it will do here.

The best version of this uses data you already have access to the moment OAuth completes. Say an affiliate app reads the store name, the product count, and recent order volume, and opens with "Your store had orders from 412 customers in the last 30 days. Here is what a referral program could do with them." A review app can count the products that have no reviews yet. A creator outreach tool for TikTok Shop can show how many products are eligible for affiliate listing. None of this needs the merchant to type anything, and it tells them in one line that the app has understood their store.

Below that, show the one setup step. Not a checklist of eight items. One step, with a button.

Shopify's onboarding guidance backs this up. It says onboarding "should be brief and direct," that a good setup "acts as a quick start, with discrete steps that are automatically marked as complete," and that you should "request information from merchants only if it's necessary." The same page puts a hard number on it: "Avoid more than five steps in your onboarding process, as additional steps can lead to merchant drop off." Five is the ceiling. One is the target for the first session.

Which setup step actually matters?

Every app has one action that turns it from installed to working. Find it, put it on the first screen, and default everything around it.

Examples from the categories I have worked in:

• Affiliate and referral apps: create the first program and generate the first shareable link. Commission rate, cookie window, and payout method can all be defaults the merchant edits later.
• Creator outreach tools for TikTok Shop: connect the seller account and pick one product to pitch. Message templates can ship pre-written.
• Email and SMS apps: connect the sending identity and import the customer list. The first flow can be a template the merchant turns on, not one they build.
• Review apps: import existing reviews, or send the first review request to recent customers.

The test for whether you have found the right step: after the merchant does it, can you show them something that happened in their store? If the answer is no, you have picked a settings step, not the activation step.

When I design these screens I write the step as a sentence the merchant would say. "I want to pay my customers 10% for referring a friend." The form then only asks for what that sentence does not already decide. In that example, nothing. The 10% is a default they can change.

How do you show the merchant a real result from their own data?

A result is something that changed in the store, or something the app found in the store. Both count. "Your referral link is live on your thank-you page" is a result. "We found 1,840 customers who ordered twice and have never been asked to refer anyone" is also a result, and it needs nothing from the merchant but the install.

The second kind is underused. Most apps read orders, customers, and products only after the merchant has configured something. Read them before. Show the merchant what the app sees, then ask them to turn it on.

This is also why I argue against sample data on the first screen when real data is available. Sample data tells the merchant what the app looks like for someone else. Real data tells them what it will do for them. I cover that choice in more detail in the guide on empty state design.

The 2016 Shopify Partners post on improving your app's onboarding flow makes a related point with its "show, don't tell" rule and its advice to "demonstrate key features, not every feature." The post is from 2016 and some of its tooling advice has dated, but the principle holds. The app working on the merchant's store beats any tooltip tour.

What should you defer until after the first result?

Anything not required for the first result goes behind the result, not in front of it. Things that are almost always deferrable:

• Branding the widget, email, or landing page. Ship it with the store's name and a neutral style.
• Payout and billing details for the app's own features, such as how affiliates get paid. Needed before the first payout, not before the first link.
• Integrations with Klaviyo, Postscript, or other apps. Offer them once the merchant has data worth syncing.
• Notification settings. Default to sensible ones.
• The plan picker, if your pricing allows a free tier or a trial. If a plan must be picked on install, keep it to one screen with a recommended default.

Shopify's guidance says non-essential onboarding should be dismissible and finishable later. I would go further. The deferred steps should live in a persistent setup guide on the home page, with the completed ones already ticked, so the merchant sees progress they did not have to earn. There is a separate guide on onboarding checklist design that covers ordering those steps by value rather than by setup order.

How do you know the onboarding is working?

Three numbers, all available from your own events plus the Shopify install and uninstall webhooks:

1. Share of installs that reach the first result in the first session. This is your time-to-first-value number. The activation event itself usually sits later, at the first affiliate or the first referred order, and the guide on SaaS activation rate covers how to pick it and what a reasonable number looks like.
2. Median time from install to first result. If it is measured in days, the first screen is not doing its job. I use PostHog funnels for this, with the install webhook as the first step and the result event as the last.
3. Uninstalls within seven days of install, split by whether the merchant reached the result. If merchants who reached the result still uninstall at the same rate as those who did not, the result you chose is not the one they care about. The guide on reducing Shopify app uninstalls goes deeper on that split.

In my experience the biggest leak is almost never OAuth. It is the first screen, where the merchant arrives, sees nothing that reflects their store, and leaves to check their email.

Where to start

1. Open your app in a fresh development store and count the clicks from install to the first thing that visibly happens in the store. Write the number down.
2. Name the one setup step. If you cannot name it in one sentence, the app has a positioning problem before it has an onboarding problem.
3. List every field on the current setup screens and mark each one as "needed for the result" or "could be a default". Move the defaults to settings.
4. Add one line to the first screen that uses the merchant's own store data, even if it is only the order count.
5. Set up the install-to-result funnel in your analytics and look at it weekly.