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?

Does a non-technical team need Function terminology to brief an agency?

No. A non-technical team needs its business rule, written in the words the team already uses, not the vocabulary of Shopify Functions, the custom code Shopify runs at checkout. An agency can translate a rule into Shopify's code, but it cannot invent the rule. In our judgment, a vague rule is the single largest source of change orders on this kind of work. Who should build and own the Function is the decision that comes first; this brief is what you hand whoever you choose.

Write the rule as cases a new hire would understand, 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, because each case becomes a test the agency can price. Deploi's Build vs. Buy record on custom discount types asks for the same thing as a table: inputs and outputs that marketing signs off on, including what happens when the rule meets another discount (October 2026).

Which facts about your data and carts should the brief list?

The brief should list every fact your discount or checkout rule reads, where each fact is stored today, and who maintains it. Typical facts are a customer tag, a wholesale company, a product tag, a collection, a metafield (a custom data field), the market, line quantities, the cart total and the delivery method.

Shopify's limits turn that list into constraints. The query that fetches a Shopify Function's data is capped at 3,000 bytes and a cost of 30 (shopify.dev, October 2026). Each metafield, tag or collection check costs 3 of those 30, so one input query can make at most ten such checks (Deploi arithmetic). Lists passed into the query can't exceed 100 elements, and metafield values over 10,000 bytes are not returned. That means a 400-product exclusion list read at checkout needs redesigning. Deploi's record on input query limits recommends small, purpose-built metafields instead (October 2026).

Add two more lines:

• Facts that live outside Shopify. Network access for discount Functions is limited to custom apps on Shopify for enterprises (Shopify's network access guide, October 2026). So on Shopify Plus, data held in an enterprise resource planning (ERP) system gets copied into Shopify before checkout.
• Your largest realistic cart, in line items. Say whether wholesale carts are larger, because cart size drives the Function's programming language and part of the quote.

How should the brief describe collisions with other discounts?

The brief should say, case by case, what happens when your rule meets every other discount that can reach the same cart. Shopify sorts discounts into product, order and shipping classes, and each discount combines only with the classes you select (Shopify Help Center, October 2026). Customers can use up to 5 product or order discount codes and 1 shipping discount code on one order, per Shopify's combining discounts page (October 2026). A store can also run up to 25 active automatic discounts. So the collision section of the brief answers four questions:

1. What happens if the customer also enters a discount code?
2. What happens if an automatic discount already applies?
3. What happens if a business-to-business (B2B) catalog price already applies?
4. Which discount wins, and is that the same answer in every case?

In our judgment, collisions are the most commonly missing section of a brief and the most commonly disputed one after launch. Deploi's Build vs. Buy record on discount stacking scores this layer CUSTOMIZE (October 2026). In that record, Shopify's combination settings carry the common matrix, and a Shopify Function enforces what checkboxes cannot, such as a cap on an order's total discount.

What should the brief say about failures and changes after launch?

The brief should say what the rule does when it fails, who hears about it, and who changes it later. A Shopify Function can fail outright, or it can run and return a wrong result because of a bug (Shopify monitoring guide, October 2026). That guide describes no merchant-facing alert, so the brief answers four questions:

• If the rule cannot be evaluated, does the cart get full price, or does checkout stop?
• Who is alerted, and through which channel? Name a person, and read why alerting needs its own line in the quote.
• Which numbers will change, and who edits them after launch?
• Who keeps the Function current? Shopify supports each API (application programming interface) version for at least 12 months (Shopify's versioning guide, October 2026), so the yearly upkeep a custom Function carries needs a named owner.

What does a complete one-page brief look like?

A complete Shopify Function brief is one page: the rule as cases, the facts it reads, its collisions, what happens on failure and who edits it, plus three lines that are not about the rule:

• Your plan, in line one. Only Shopify Plus stores can use custom apps that contain Shopify Function APIs (application programming interfaces), per shopify.dev (October 2026). Stores on any plan can use public App Store apps that contain functions.
• The apps you rejected, and why. Function apps from the App Store cover many common rules, so naming the ones you tried saves a discovery call.
• Any Shopify Script the rule replaces. Shopify deprecated Scripts on 30 June 2026 (Shopify Help Center, October 2026). The admin's Shopify Scripts customizations report can list each Script's name, description and source file links. Export it as a CSV (comma-separated values) file and attach it.

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, in line items:
Collisions (codes, automatic discounts, wholesale catalog prices, other apps):
On failure (full price or stop, and who is alerted):
Who edits the numbers and keeps the Function current:
Our plan (Plus or not):
Apps we evaluated, and why we passed:
Scripts this replaces (attach the customizations report):

When should you not send the brief yet?

Hold the Shopify Function brief until the rule, the data and your Shopify plan are settled, because an agency prices every open question as risk.