CartShield Documentation
Detailed guide to rule configurations, server-side function architecture, and error handling.
1. Technical Architecture & Shopify Functions
CartShield uses Shopify's modern Checkout Validation API (purchase.validation.run). Unlike legacy script tag apps, checkout validation runs as a WebAssembly (Wasm) binary inside Shopify's core checkout pipeline.
2. Core Validation Rule Engines
A. PO Box & Postal Locker Restriction
Interprets delivery address lines (Address 1, Address 2) using comprehensive regular expression patterns targeting variations of Post Office boxes, Army Post Offices (APO/FPO/DPO), and private parcel lockers.
B. Add-on & Sample Kit Dependency
Protects sample items, swatch kits, or deeply discounted promotional gifts. Validates that if a restricted SKU is in the cart, at least one qualifying catalog item from an allowed collection is also present.
C. B2B / Wholesale Case Multiples
Guarantees wholesale orders conform to factory master carton counts. Evaluates the line item quantity with modulo arithmetic (qty % step === 0) and rejects arbitrary quantities.
D. Collection Minimum / Maximum Spend
Enforces subtotal thresholds on specific clearance, refrigerated, or export-only collections before allowing the order to complete.
3. Error Placement & Localization
CartShield delivers errors in two distinct targets depending on rule context:
- Target Field Error (
$.cart.deliveryGroups[0].deliveryAddress.address1): Highlighted directly under the buyer's shipping address field with red contextual feedback. - Page-Level Banner Error: Prominently displayed at the top of the checkout form for cart-level quantity or spending conditions.
Error copy is fully customizable in the CartShield admin and supports emoji indicators for clear customer guidance.
4. Shopify Metafield Storage Schema
To ensure sub-5ms evaluation without database roundtrips during checkout, all active rules are synced to the shop metafield:
Key: rules_config
Type: json