Architecture

Data Flow

AutoCart operates across three Shopify surfaces, each with different capabilities and constraints:

1. Storefront (Theme Extensions)

The standard theme extension runs on storefront pages where its block is installed. It:

• Reads your automation rules
• Populates window.autoCartConfig with all rule data, product info, and settings
• Intercepts cart API calls (/cart/add, /cart/change, optionally /cart/update)
• Evaluates rules against the current cart state
• Displays gift picker modals when rules match

The Progressive app embed separately:

• Reads Tiered and Cyclic rules from app-owned metaobjects
• Watches cart API changes made through fetch and XMLHttpRequest
• Resolves qualifying products by explicit selection, product tag, or collection
• Synchronizes Progressive gift lines and quantities
• Reloads the page or invokes the configured callback after its own cart mutations

Key constraint: Storefront extensions cannot access checkout-specific data such as payment methods and shipping addresses. Progressive product-tag qualification reads product metadata; this is separate from customer-tag conditions.

2. Checkout (Checkout Extensions)

The Checkout Gift extension re-evaluates standard rules with richer context:

• Accesses customer identity, tags, and company info
• Reads delivery groups and shipping addresses
• Evaluates payment method conditions
• Can apply discount codes programmatically
• Manages a queue for sequential cart mutations

Key behaviors:

• Auto-clean: Removes products from expired or deleted rules
• Scope filtering: Only evaluates rules scoped to checkout or global (not storefront-only)
• doNotEvaluateStorefrontRule: Optionally preserves products added by storefront-only rules

The Checkout Progressive Extension runs a separate reactive pipeline for Tiered and Cyclic automations. It resolves product qualification inside checkout and queues all line additions, removals, and quantity changes sequentially.

3. Discount Function

The discount function runs server-side on Shopify's infrastructure:

• Reads cart line attributes to determine which discounts to apply
• Applies product-level discounts as configured
• Runs on every checkout calculation
• No network access — purely input/output based

Rule Evaluation

Rules are evaluated using a conditions engine. The evaluation flow:

Automation Rule
        │
        ▼
  Build Input Object
  (cart lines, cost, customer, attributes, discounts, delivery groups)
        │
        ▼
  Evaluate conditions against input
        │
        ├── true  → Add/keep products, apply discounts
        └── false → Remove products (if keep=false)