The Cart Validation Function API
Shopify's Cart and Checkout Validation Function API gives developers the ability to enforce business rules directly within the checkout pipeline. Unlike theme-level JavaScript validation that can be bypassed by savvy users or headless storefronts, Function-based validation runs server-side on Shopify's infrastructure and cannot be circumvented. The Function receives the full cart context — line items, customer details, shipping address, and cart attributes — and returns either an approval or a list of validation errors that block the checkout from proceeding. This makes it the single source of truth for what constitutes a valid order.
The Function's input query is written in GraphQL, allowing you to request exactly the cart data your validation logic needs. Your validation code then evaluates this data against rules that can be hardcoded, stored in metafields for merchant configurability, or fetched from app-owned metaobjects. When a rule is violated, the Function returns an error with a localized message and a target indicating which cart line or attribute triggered the failure. Shopify surfaces these errors in the checkout UI automatically, giving customers clear feedback on what needs to change before they can complete their purchase.
Case Study: Preventing Invalid Product Combinations
A supplement brand selling through Shopify needed to prevent customers from purchasing certain product combinations that could cause adverse interactions. Their catalog included products tagged with interaction groups, and any two products from the same conflict group should not appear in the same cart. The validation Function queries each line item's product tags, cross-references them against a conflict matrix stored in a metaobject, and returns a targeted error on the offending line items if a conflict is detected. This replaced a fragile JavaScript-based approach that only worked on their primary theme and failed entirely on their wholesale headless channel.
Another merchant — a B2B electronics distributor — required minimum order quantities that varied by customer segment. Wholesale customers had to order at least 10 units per SKU, while retail customers had no minimum. The validation Function checks the customer's B2B company metafield to determine the segment, then evaluates each line item's quantity against the segment-specific minimum. If any line falls below the threshold, the error message specifies both the product name and the required minimum, so the buyer knows exactly what to adjust. This rule applies universally across their online store, POS, and draft orders created by sales reps.
Geographic Restrictions and Quantity Caps
Merchants selling regulated goods — alcohol, certain cosmetics, age-restricted items — frequently need to restrict purchases based on the shipping destination. A wine retailer used a cart validation Function to check the shipping address state or province against a list of regions where they hold distribution licenses. If the customer's shipping address falls outside the permitted regions, the Function blocks checkout with a clear message explaining the geographic restriction. The permitted regions list lives in a metafield that the merchant's compliance team updates directly from the Shopify admin whenever their licensing changes, with no code deployment required.
Quantity caps are another common pattern. A limited-edition sneaker brand caps purchases at two pairs per style per customer to combat resellers. The validation Function checks each line item's quantity and, critically, also queries the customer's order history via metafields to prevent repeat purchases of the same limited item across multiple orders. This layered approach — combining cart-level and historical validation — provides a much stronger defense against bulk buying than simple cart quantity limits alone. The Function's server-side execution means these rules hold regardless of which sales channel the order originates from.
If your store has business rules that need to be enforced at checkout — product restrictions, quantity limits, geographic compliance, or any custom logic — the Cart Validation Function API is the right tool. Let's talk about building validation rules that protect your business without compromising the customer experience.