Custom Settings

Reference for the additionalSettings passed through the Custom Settings textarea.

Overview

The Custom Settings textarea in the Shopify theme editor allows passing advanced configuration options to AutoCart. These values are injected into window.autoCartConfig.additionalSettings and control various behaviors of the AutoCart engine.

These settings are not exposed as individual fields in the theme editor. They must be entered as comma-separated key-value pairs in the Custom Settings textarea field.

How to Configure

In the Shopify theme editor, find the Custom Settings textarea and enter values like:

manualOpen: true, showPrice: true, currencyRate: true

For array values:

ignorePages: ["/pages/about", "/pages/faq"]

The content is injected directly into a JavaScript object: { <your values> }, so the syntax follows JavaScript object property syntax.

Settings Reference

Key	Type	Default	Description
`manualOpen`	`boolean`	`false`	When `true`, prevents AutoCart from automatically opening the gift picker modal. Use this when you want to trigger the modal programmatically from custom code.
`openModalEmpty`	`boolean`	`false`	When `true`, the gift picker modal opens with no variants pre-selected, even if matching products are already in the cart. Useful for scenarios where you want the customer to explicitly re-confirm their gift selection.
`persistClosedWindow`	`boolean`	`false`	When `true`, if the customer dismisses (closes) the AutoCart modal, it will not reappear during the same session.

Callback

Key	Type	Default	Description
`onAutocartUpdateCallback`	`boolean`	`false`	When `true`, fires the Storefront onUpdate callback after every AutoCart cart update completes. The callback function itself is defined in the AutoCart app → Settings page under "Storefront onUpdate callback". Use this to trigger custom analytics events, UI updates, or any post-cart-update logic.

Product Card Display

These settings control what price information is shown on product cards inside the gift picker modal.

Key	Type	Default	Description
`showPrice`	`boolean`	`false`	Show the product price on gift picker cards.
`showCompareAtPrice`	`boolean`	`false`	Show the compare-at (original) price alongside the current price. Useful for displaying crossed-out prices.
`showDiscountedPrice`	`boolean`	`false`	Show the discounted price on gift picker cards. Relevant when an automatic discount is configured for the rule.

Currency

Key	Type	Default	Description
`currencyRate`	`boolean`	`false`	Enable currency rate conversion for displayed prices. When enabled, prices are converted using Shopify's market currency rates. Required for multi-currency stores.

Cart Interception

Key	Type	Default	Description
`enableUpdateEvent`	`boolean`	`false`	By default, AutoCart intercepts `/cart/add` and `/cart/change` routes. When `true`, it also intercepts `/cart/update`. Enable this if your theme uses the update endpoint for cart modifications (some themes use this instead of change).

UI Behavior

Key	Type	Default	Description
`removeDisabledButtons`	`boolean`	`false`	When `true`, variant buttons that are unavailable (out of stock) are completely removed from the picker UI instead of being shown in a disabled state.

Page Exclusions

Key	Type	Default	Description
`ignorePages`	`string[]`	`null`	An array of URL path patterns where AutoCart should be completely disabled. When the current page URL matches any pattern in this array, AutoCart will not evaluate rules or intercept cart actions.

Example:

ignorePages: ["/pages/about", "/pages/contact", "/cart"]

Complete Example

A full custom_settings configuration using all available options:

manualOpen: false,
openModalEmpty: false,
persistClosedWindow: true,
onAutocartUpdateCallback: true,
showPrice: true,
showCompareAtPrice: true,
showDiscountedPrice: false,
currencyRate: true,
enableUpdateEvent: false,
removeDisabledButtons: false,
ignorePages: ["/pages/wholesale"]

When enableUpdateEvent is enabled, the /cart/update route is added to the list of intercepted cart API calls.

Programmatic Invocation

AutoCart exposes two ways to manually trigger the gift picker from your own custom code.

`window.autoCartConfig.__autocart()`

Once AutoCart has initialized, a function is available at window.autoCartConfig.__autocart() that opens the gift picker modal programmatically. This is useful when you want to trigger the modal from a custom button, link, or any other UI element in your theme.

Example — Custom button:

<button onclick="window.autoCartConfig.__autocart()">
  Pick your free gift
</button>

Example — JavaScript:

// Open the gift picker modal from custom code
document.getElementById('my-custom-trigger').addEventListener('click', () => {
  if (window.autoCartConfig?.__autocart) {
    window.autoCartConfig.__autocart();
  }
});

This function is only available after AutoCart has fully initialized. If you call it too early, it may be undefined. Always check for its existence before calling.

`handle-autocart` Custom Event

You can also trigger a full AutoCart re-evaluation by dispatching a custom DOM event:

document.dispatchEvent(new Event('handle-autocart'));

This re-runs the entire AutoCart evaluation pipeline — re-reading all rules, re-evaluating conditions against the current cart, and updating the gift picker accordingly. This is useful after making external cart changes that AutoCart wouldn't automatically detect.

Difference: __autocart() only opens the gift picker modal with the current state. The handle-autocart event re-evaluates all rules from scratch.

On this page