How do we write a clear brief for an agency to scope a custom Shopify Function, if we don't know the technical terms ourselves?
A usable Function brief answers five questions in plain business language: what the rule reads, what it outputs, what happens when it collides with another discount, what happens when it fails, and who edits the numbers later. Shopify's own limits turn two of those into hard constraints: 200 line items and a 3,000 byte input query (shopify.dev, September 2026).
You do not need the technical terms. You need the rule.
An agency can name the Function API. It cannot invent your business rule, and a vague rule is the single largest source of change orders on this kind of work. Write the brief in the language your team already uses.
The five sections, with what to actually write
1. The rule, in sentences a new hire would understand.
Write it as cases, not as a description. "Customers tagged wholesale get 15% off orders over $500. Customers tagged wholesale-tier-2 get 20% off with no minimum. Nobody gets both." Three sentences like that beat a page of prose.
Include the numbers you expect to change and the numbers you do not. The agency will make the first group configurable and the second group constants, and that decision drives your cost forever.
2. What the rule needs to know, and where that lives today.
List every fact the rule reads: customer tag, company, product tag, collection, metafield, market, line quantity, cart total, delivery method. Then, for each one, say where it is stored now and who maintains it.
This is where Shopify's limits become your constraints. The Function's input query is capped at 3,000 bytes excluding comments, list-type field arguments cannot exceed 100 elements, metafield values over 10,000 bytes are not returned, and maximum input query cost is 30 (per shopify.dev, September 2026). A rule that needs a 400-SKU exclusion list read at checkout is a rule that needs redesigning, and better to learn that in the brief than in week four.
3. Cart shape.
State your largest realistic cart in line items, and say whether wholesale carts are larger. Shopify's Function resource limits are dynamic "up to 200 line items," with 11 million instructions, 128 kB input and 20 kB output at that size (per shopify.dev, September 2026). Shopify recommends Rust over JavaScript specifically "to avoid your function failing with large carts." Your line-item number is the single fact that determines the language choice and a meaningful part of the price.
4. Collisions and precedence.
The most commonly missing section and the most commonly disputed one. Answer these:
- What happens if the customer also has a discount code?
- What happens if an automatic discount already applies?
- What happens if a B2B catalog price already applies?
- Which wins, and is that the same answer in every case?
5. Failure and ownership.
- What should happen if the rule cannot be evaluated? Full price, or block the cart?
- Who finds out, and how? Shopify stores function runs in the Dev Dashboard, truncates logs at 1 kB, and ships no merchant-facing alert (per shopify.dev, September 2026). Name the person and the channel.
- Who edits the numbers in six months, and do they have admin access or a deploy pipeline?
Two things to put in the brief that are not about the rule
- Your plan. Custom apps containing Functions are Plus-only (per shopify.dev, September 2026). If you are not on Plus, say so in line one, because it changes the entire answer.
- What you have already tried. If you looked at App Store apps and rejected them, say which and why. That one paragraph saves a discovery call and tells the agency you have done the cheap work.
A one-page template
RULE (as cases)
...
NUMBERS THAT WILL CHANGE
...
NUMBERS THAT WILL NOT
...
FACTS THE RULE READS (fact / where it lives / who maintains it)
...
LARGEST REALISTIC CART (line items)
...
COLLISIONS (code / automatic / B2B catalog / each other)
...
ON FAILURE (full price or block, and who is alerted)
...
WHO EDITS THE NUMBERS AFTER LAUNCH
...
OUR PLAN (Plus or not)
...
APPS WE EVALUATED AND WHY WE PASSED
...When NOT to send a brief yet
- When the rule is still being argued about internally. Agencies price disagreement as scope.
- When nobody has checked the App Store. A brief for work an app already does is an expensive way to learn that.
- When the facts the rule needs are not maintained anywhere. If the customer tags do not exist yet, the first project is the tagging, not the Function.
The Deploi point of view
Our own position, from building on Shopify. Separate from the facts above.
- Our take: the collision section is the one that separates a brief that gets an accurate quote from one that gets a range. Write it even if the answer is "we have never thought about that," because writing "we have never thought about that" is itself information an agency can price.
- What we’ve seen: briefs that specify the happy path and omit precedence produce quotes that are accurate for the happy path. The gap surfaces in UAT, as a change order, at the worst possible moment in the schedule.
- Where we disagree: the usual advice is to learn the vocabulary before you brief. Do not. A brief written in Function API terminology by someone who just learned it is harder to quote than a brief written in your own words, because now the agency has to reverse-engineer what you meant as well as what you need.
- What this page adds: the specific Shopify limits that turn business questions into brief sections, the collision checklist, and a template a non-technical stakeholder can fill in without knowing what a Function target is. The parent decides who to hire; this page is what you hand them.
Reviewed by Martin Dejnicki, Director of SEO & AI Search. Facts verified 2026-09-14.
Where we worked this out
Our decision records