Theme Extension

Overview

The theme extension is the primary storefront integration for AutoCart. It consists of two app blocks that you can add to your Shopify theme.

App Blocks

Automatic Mode

This block is added to your theme and runs automatically. It:

• Reads all your automation rules
• Automatically evaluates rules and manipulates the cart without user interaction
• Displays a gift picker modal when rules require customer selection

Best for: Stores that want fully automatic cart manipulation without a trigger button.

Button Mode

This block renders a visible button in your theme. It:

• Reads all your automation rules
• When clicked, opens the gift picker modal
• Supports both "automatic" and "button" action variants

Best for: Stores that want to give customers a visible button to open the gift picker (e.g., on product or cart pages).

Configuration Object

Both blocks populate window.autoCartConfig with the following structure:

window.autoCartConfig = {
  // Mode
  actionVariant: "automatic" | "button",
 
  // UI Labels (from block settings)
  buttonLabel: string,
  modalTitle: string,
  modalSubtitle: string,
  backButton: string,
  nextButton: string,
  confirmButton: string,
  denyButton: string,
  closeButton: string,
  variantLabel: string,
  variantDescription: string,
  variantSelectButton: string,
  variantSelectPlaceholder: string,
  cornerLabel: string,
  confirmModalTitle: string,
  confirmModalDescription: string,
  loadingToastTitle: string,
  updateToastTitle: string,
  updateToastDescription: string,
 
  // Behavior
  debug: boolean,
  manualReload: boolean,
  excludedDiscounts: string,
 
  // Custom settings (see Custom Settings page)
  additionalSettings: {...},
 
  // Customer data
  customer: { id, email, orders_count, tags } | null,
};

Scope Filtering

AutoCart rules can be scoped to run on specific surfaces:

• Rules scoped to "checkout" only run at checkout
• Rules scoped to "global" run on both storefront and checkout
• Rules with no scope (or scoped to "storefront") run only on the storefront

Next Steps

• Block Settings — Merchant-configurable settings in the theme editor
• Custom Settings — Advanced additionalSettings reference