Progressive Theme Extension
Storefront app embed for Tiered and Cyclic Progressive gift automations.
Overview
The AutoCart Progressive theme app embed evaluates Progressive gift rules on the storefront. It is separate from the standard AutoCart blocks and handles both automation strategies:
- Tiered — unlocks configured gifts as the cart reaches successive thresholds
- Cyclic — repeats a gift quantity each time the cart meets the configured threshold, up to an optional cycle limit
Progressive functionality is available on the Advanced and Ultimate plans, including their annual variants. When the Progressive entitlement metafield is inactive, the embed receives no rules and does not add gifts.
Setup
- Open Online Store → Themes → Customize in Shopify admin.
- Open App embeds.
- Enable AutoCart Progressive.
- Choose a Cart refresh method.
- Save the theme.
The embed must be enabled for Tiered and Cyclic rules to run on the storefront. It can be enabled alongside the standard AutoCart theme block.
How It Works
- Active Progressive rules are rendered from app-owned metaobjects into
window.autocart.progressive. - A cart observer watches successful
/cart/add,/cart/change,/cart/update, and/cart/clearrequests made throughfetchorXMLHttpRequest. - After a cart change, the extension reads the latest
/cart.jsonstate. - It evaluates Tiered or Cyclic thresholds after excluding AutoCart gift lines.
- It removes outdated or no-longer-qualified gifts with
/cart/update.jsand adds newly qualified gifts with/cart/add.js. - If the extension changed the cart, it uses the selected refresh method.
The engine also evaluates once on page load. Internal cart mutations use the original, unpatched fetch implementation so they do not recursively trigger the observer.
Qualifying Products
Each step can calculate progress from:
| Qualifier | Behavior |
|---|---|
| All products | Every non-gift cart line counts. |
| Specific products | Only selected product variants count. |
| Product tags | Tags are resolved for the products currently in the cart after cart updates. |
| Collections | Collection membership is resolved for the products currently in the cart after cart updates. |
If tag or collection metadata cannot be retrieved, the affected rule is not changed during that evaluation. This avoids incorrectly removing or awarding gifts from incomplete qualification data.
Gift Quantities and Discounts
Each gift product has its own quantity. Cyclic rules multiply that quantity by the number of earned cycles. A step can optionally apply a fixed or percentage discount, with 100% percentage discount as the default. The appliesToEachItem option controls whether a fixed discount applies to every awarded item or to the line as a whole.
Theme Settings
| Setting | ID | Type | Default | Description |
|---|---|---|---|---|
| Cart refresh method | refresh_method | select | page_reload | Page Reload reloads after a Progressive cart mutation and works with every theme. Callback Function executes the callback configured in AutoCart settings so supported themes can refresh their cart UI without a full reload. |
| Debug | debug | checkbox | false | Logs Progressive configuration, evaluation, and mutation details to the browser console. |
The refresh action only runs when Progressive actually adds, removes, or replaces a cart line. A no-op evaluation never reloads the page or runs the callback.
Events API
When Callback Function is selected, this embed publishes the same autocart:ready, autocart:before, autocart:updated, and autocart:error events as the standard storefront extension. See the shared Events API reference.
Progressive event entries use rule.scope values of "tiered" or "cyclic". Gift lines can also be recognized by _autocart_prog, _ac_tier, and _ac_cyclic properties.