Custom checkout logic with Functions: three worked examples

A Function is a small piece of code you write, compiled to WebAssembly, that Shopify executes at a defined point in its own checkout flow. It receives a structured input — the parts of the cart, customer and shop you asked for in an input query — and returns a structured output describing what should change: these discounts apply, hide that shipping method, block this checkout, group those lines into a bundle.

That "inside Shopify" part is the whole value proposition, and it is worth being concrete about why. Logic in your theme runs in the customer’s browser, where it can be inspected, edited or skipped, and it disappears entirely at the checkout step. Logic in an app that listens for webhooks runs after the order exists, which is too late to prevent anything. A Function runs before the order exists, on Shopify’s side of the boundary, and its answer is the one that counts.

Shopify documents the available APIs and the order they execute in: cart transform, discounts, fulfilment constraints, order routing, pickup point and local pickup delivery option generators, delivery customisation, payment customisation, and cart and checkout validation. Between them they cover most of the checkout behaviour that used to require Shopify Scripts, plus several things Scripts never could.

The brief that arrives most often: trade customers get tiered pricing by volume, the tiers differ by product group, and none of it may stack with a seasonal promotion already running on the site. Every part of that is ordinary retail logic and none of it fits in the discount form.

The shape of the Function is straightforward. Your input query asks for the cart lines, the merchandise and its product, the customer and whichever metafields hold the configuration — tier thresholds on the product or collection, the customer’s trade group on the customer record. The code walks the lines, works out which tier each qualifying line reaches, and returns discount targets with amounts.

Three details decide whether it survives a real promotion.

Put the configuration in metafields, not in the code. A tier table compiled into the binary means every threshold change is a deploy. The same table in metafields is editable by the person who owns pricing, and the Function reads it through the input query. This is the single biggest difference between a Function that works for a year and one that becomes a ticket every fortnight.

Respect the input query budget. The input query is limited to 3000 bytes excluding comments, with a maximum calculated cost of 30 — exceed it and validation fails with "Query has complexity of <cost>, which exceeds max complexity of 30". Metafields larger than 10,000 bytes are not returned at all, which rules out stuffing an entire price book into one JSON metafield and reading it per request. If your configuration is genuinely large, it belongs on the objects it describes rather than in one place.

Watch the output budget. Shopify caps function output at 20 kB for carts up to 200 line items and states plainly that this "doesn't support bulk price transformations across all line items". A trade order with a hundred lines and a discount emitted per line will run into that. Target the lines that need it, group where the API allows grouping, and test with the largest cart your wholesale customers actually place rather than with a cart of three.

The thing a Function will not solve is which discounts combine with which — that is configured on the discount, and it is where most promotions actually break. That is a separate problem with its own answer.

Second brief: next-day delivery must disappear when the cart contains a made-to-order item, an aerosol, or anything shipping from the slower warehouse; and the remaining option should be renamed so the customer understands why.

This is a delivery customisation function — Shopify’s documented examples include hiding and renaming delivery options. The input query asks for the cart lines and a metafield on each product marking it as restricted, plus the delivery groups and their available options. The output hides or renames.

The interesting part is what you cannot do, and it catches teams out every time. There is no clock. Shopify does not allow nondeterminism in functions, explicitly including clock functionality, so a Function cannot ask what time it is and therefore cannot decide on its own that the cut-off for next-day has passed.

That is not a dead end, it is a design instruction: time-dependent decisions are made outside the Function and passed in as data. The cut-off logic lives in the theme or in an app that writes a cart attribute — *dispatch window closed*, or the computed delivery date — and the Function reads the attribute and acts on it. Shopify’s own guidance points the same way, noting you can pre-populate data using metafields on products and customers, or pass data using cart attributes.

Worth saying clearly, because this pattern is the answer to a whole class of requirements. Anything a Function needs to know that is not a property of the cart, the customer or the shop has to be put where the Function can see it — computed upstream, stored in a metafield or an attribute, read as input. Once a team internalises that, half of the "can Functions do X" questions answer themselves.

One honest caveat: pushing a rule into a cart attribute means the value arrives from the storefront, which is exactly the layer a Function exists to be independent of. Use attributes for things where being wrong is a poor experience rather than a loss — a delivery date, a cut-off — and keep anything with money or eligibility attached in metafields the customer cannot influence.

Third brief: trade accounts have a minimum order value; certain products cannot ship to certain regions; and a configurable item is invalid unless its accompanying options are present. Today all three are enforced with JavaScript on the cart page, and every week somebody gets through anyway.

A cart and checkout validation function is the right tool — Shopify’s documented example is blocking progress on a checkout when cart line quantities exceed a limit. It returns errors, and an error stops the checkout. Not a warning, not a banner someone dismisses: the customer cannot proceed.

What makes this worth the effort is not the rule, which is trivial in any language. It is that the rule now has one home. The cart page check, the checkout check and the "we caught it in ops" check collapse into a single function running on Shopify’s side, and the failure mode changes from "an invalid order exists and someone must ring the customer" to "the order was never placed".

Two things to get right. Write errors a customer can act on. "Validation failed" is a support ticket; "Trade orders have a minimum of X units — add Y more to continue" is a resolved problem. The message is the entire interface of this Function, and it deserves the same attention as any other checkout copy. Decide what happens to a cart that becomes invalid after the fact — stock moves, a customer is reassigned to a different account, a product is restricted. The Function will correctly block a checkout for a cart the customer assembled in good faith last week, so the storefront should ideally be showing the same rule long before they reach checkout. The Function is the enforcement layer; it is not a substitute for telling people earlier.

Before any of this is scoped, one sentence in Shopify’s documentation decides whether the conversation is a development project or an app search: "Only stores on a Shopify Plus plan can use custom apps that contain Shopify Function APIs." Public apps distributed through the App Store are available on all plans.

So for a store not on Plus, a bespoke Function is not a line item on a quote — it is a plan upgrade plus a development project. That changes the maths completely, and in most of those conversations the right answer is an app from the store that already does something close enough, or a simplification of the rule so the native discount and shipping settings can express it.

That second option gets dismissed too quickly. A surprising number of Function briefs describe a rule that exists because of an operational constraint nobody has revisited, or a pricing structure that grew one exception at a time. "Three tiers instead of seven" is not a compromise if nobody can explain what tiers four through seven are for, and it is considerably cheaper to maintain than any amount of WebAssembly.

Where a Function does earn its cost, it earns it decisively: logic that cannot be bypassed, that survives theme changes, that runs in checkout rather than around it, and that moves a rule out of four places into one. Those are durable properties, and they are the reason this is one of the few pieces of Shopify’s extensibility surface we would recommend building on without much hesitation — once the plan question is settled.

• Shopify store development
• Discount logic that survives your next promotion
• Checkout UI extensions: what belongs in checkout and what does not