How to Brief a Developer for a Custom Shopify App

A good brief does not need to be a specification. It needs to describe the job clearly enough that a developer can tell you how they would approach it, what Shopify allows for your store, and what they need from you. Shopify’s own advice on hiring a Partner starts in the same place: learn the key terms, gather examples from similar businesses, and define your budget, timeline and expected outcomes. Contacting a Partner does not commit you to hiring them.

If you are not yet sure a custom app is the right answer, read custom Shopify app or off-the-shelf first. Flow, Functions or an existing app may already cover the job.

What to put in the brief

A few lines on each point is enough. Skip anything you do not know yet.

1. Today. Who does the job, step by step, and in which tools.
2. The pain. Where the time goes and where mistakes happen.
3. Done. What someone sees when it works.
4. Systems and data. What it needs to read or change: orders, products, stock, customers, or something outside Shopify.
5. Rules. Which actions must never happen without a person’s approval, and who approves them.
6. Stores and plans. Which stores are involved and which Shopify plan each is on.
7. Deadline, if any. A date you are working toward, such as a Shopify change or a launch.

An example brief

Here is what that looks like for a made-up but typical case. Notice how short it is.

Today: Every morning Sara exports unfulfilled orders, deletes columns in Excel and emails the file to our warehouse. Rush orders are marked by hand.

Pain: About 40 minutes a day. Rush orders get missed when the tag is spelled differently.

Done: At 8:00 the warehouse gets a file with our columns, rush orders on top, and Sara only checks it.

Systems and data: Shopify orders and tags. The warehouse accepts CSV by email or SFTP.

Rules: Nothing in Shopify changes automatically. Sara approves any order that is held back.

Stores and plans: One store, Grow plan.

Deadline: Before our December peak.

A developer can answer that brief with a concrete approach, a question or two and a rough estimate. They cannot do that with “we need an order automation app”.

Your Shopify plan changes what is possible

Several customizations depend on the plan, so put it in the brief:

• Only stores on Shopify Plus can use custom apps that contain Shopify Function APIs, the logic behind custom discounts, payment and delivery options. Public apps with functions work on any plan.
• Checkout UI extensions on the Information, Shipping and Payment steps are Plus-only; extensions on the Thank you and Order status pages work from Basic up.
• Shopify Flow’s Send HTTP request action needs the Grow, Advanced or Plus plan.
• Shopify’s custom apps page notes that custom apps needing Level 2 customer data require the Grow plan or higher. It also explains that custom apps are now created and managed in the Dev Dashboard.

If several stores are involved, say whether they belong to the same Plus organization. A custom app can only be distributed to one store or to stores in one Plus organization, which affects how the work is set up.

Give access without handing over the keys

Any outside developer needs some access to your store. Shopify’s answer is the collaborator account: a Partner gets access to your store without becoming staff, and you choose which sections they can open. Shopify’s hiring guide notes that partners may need temporary access this way, so agree on it up front.

• Give only the sections the job needs. An order export tool does not need access to themes or payments.
• Never share the store owner’s login or a staff account’s password.
• Keep a short list of who has access and why.
• Remove access when the work is done, and check the list again after each project.

For agencies managing access across many client stores, our guide to agency store access and AI tools covers the setup in more detail.

Seven questions to ask any developer

1. Which API version will it use, and who updates it? Shopify releases a new API version every three months and supports each stable version for at least 12 months.
2. What happens if a webhook is missed or arrives twice? Shopify’s webhook best practices recommend ignoring duplicates and running periodic reconciliation. Our checklist for integrations that don’t break explains why.
3. What happens to my data when I uninstall? Shopify’s API terms require developers to delete merchant data within 30 days.
4. Which actions will need a person’s approval?
5. Where does it run, and who owns the code and the data?
6. What access do you need? The answer should be a collaborator account with limited sections.
7. What happens after launch? Who fixes a bug, who handles the next API version, and how you reach them.

What a good reply looks like

A brief is the start of a conversation. A useful reply from a developer usually contains:

Part of the reply	What to look for
Approach	Where the logic will live (Flow, a Function, a custom app, an outside service) and why.
Questions	Points your brief left open. A reply with no questions often means the job was not read closely.
Access	The exact sections needed, not “full access”.
Plan limits	Anything your Shopify plan blocks, said up front.
Scope	What is included and what is not, in plain words.
Estimate	Cost and time, or a small first step to find out.
After launch	Who maintains it, and how API version updates are handled.

If two replies differ a lot, ask each developer to explain the other’s approach. The differences usually show which one understood the job.

Ownership and handover

Agree on these before work starts, not when something breaks:

• Code. Where it lives and whether you get a copy or access to the repository.
• The app itself. Which developer account it is created under, and what happens if you change developers.
• Hosting and accounts. Who pays for the server and any third-party services, and in whose name they are registered.
• Secrets. API credentials should never travel by email or chat in plain text.
• Documentation. A short page on what the app does, where it runs and how to turn it off.

For agencies: one custom app per merchant

Agencies often get the request first: a client wants something no app does. Shopify’s rules shape the answer. The API terms say a custom app may not be made available to more than one merchant, and the distribution guide defines custom distribution as a single store, or several stores in the same Plus organization, without App Store review and without Shopify’s app billing. A tool meant for many merchants is a public app, with App Store review, and the distribution method cannot be changed once chosen.

So decide early whether the work is for one client, one Plus organization or many merchants. It changes how the app is built.

Agent-based tools: prepare, then approve

Teams increasingly ask whether an AI tool could take over a routine. The safe pattern separates preparing from deciding. Sort tasks by two questions: can it be undone, and does it move money?

• Reports, checks and drafts can be handed off; the worst case is a wrong summary that a person reads first.
• Changes that can be undone can be handed off with a record of every change.
• Refunds, cancellations and anything irreversible should always wait for a person. Cancelling an order, for example, voids the payment authorization at once.

Write those lines into the brief. Our guide to approval workflows for live store changes shows how teams set up who approves what.

Data rules still apply: Shopify’s API terms do not allow merchant data to be used to train AI or machine-learning systems without consent. For background on how AI tools connect to a store, read connecting AI tools to Shopify with MCP. Note that Shopify’s Dev MCP server is for building: it connects an AI tool to Shopify’s developer docs and API schemas, runs locally and does not touch your live store.

FAQ

How detailed does a brief need to be?

A few lines per point is enough to start. A developer needs to understand the job, the data and the rules, not a full specification. The details get settled in the reply and the follow-up questions.

Should I give a developer my staff login?

No. Use a collaborator account, which lets a Partner work on your store with only the sections you choose, and remove it when the work ends.

Does my Shopify plan matter for a custom app?

Yes. Custom apps with Shopify Functions need Plus, checkout UI extensions on the Information, Shipping and Payment steps are Plus-only, and custom apps that need Level 2 customer data require Grow or higher. Put your plan in the brief.

Can an agency reuse one custom app for several clients?

No. Shopify’s API terms do not allow a custom app to be made available to more than one merchant. A tool for many merchants is a public app with App Store review.

What should happen to my data if I stop using the app?

Shopify’s API terms require developers to delete merchant data within 30 days after uninstall. Ask how the developer meets this before you start.

Send us the brief

Our page on hiring Shopify app developers covers custom apps, integrations, back-office tools and servers of your own. Agents and MCP tools built for a team’s own process are the newest kind of work there, marked as early, with a person approving risky actions such as refunds.

Have a brief, or just a few lines? Talk to us and we will reply with how we would approach it.