Theme Extension

Overview

The standard theme extension is the primary storefront integration for AutoCart. It consists of two app blocks that you can add to your Shopify theme. Tiered and Cyclic rules are handled by the separate Progressive Theme Extension app embed.

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).

Both app blocks can run either the original legacy modal or a saved Modal Designer configuration.

Legacy modal is the default and preserves the existing labels, styles, mounting behavior, and cart interaction.
Modal Designer (Advanced) loads a responsive metaobject configuration through the same extension.

The designer bundle is selected only when the shop is eligible and the configured design ID or handle resolves. Otherwise, the extension loads the legacy bundle. See Storefront Behavior for the complete selection rules.

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,
};

The Liquid runtime separately publishes the resolved design as:

window.autoCartModalDesigner = {
  enabled: boolean,
  id: string | null,
  configuration: ModalDesignConfiguration | 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
Modal Designer — Visual editor and installation guide
Custom Settings — Advanced additionalSettings reference
Events API — Events shared by the standard and Progressive storefront engines
Progressive Theme Extension — Tiered and Cyclic storefront automation

On this page