JavaScript API examples

This page shows the JavaScript API doing four jobs:

Send assignments to another tool, such as a tag manager or a data platform.
Render a custom price element, such as a bundle block ABConvert does not change.
Render a free shipping progress bar from the visitor’s shipping test.
Render an offer banner from the visitor’s offer test.

Each example is a script that runs in your theme. Treat it as a starting point: the selectors, IDs, and markup are for the store in the screenshot, so change them to match yours. The full scripts, with a playground you can run without a store, are in the ABConvert cookbook.

A mobile storefront product page with three script-rendered elements outlined and numbered: a free shipping bar above the header, a bundle block under the price, and an offer banner fixed to the bottom. The rest of the page, which the theme renders, is dimmed. — What the examples render: ① the free shipping bar, ② the bundle block, ③ the offer banner

The theme renders everything else on the page.

These scripts do not have to live in your theme. A visual editor test carries custom JavaScript per test group, so the script runs only for visitors in that test group and you end it from the ABConvert admin. Two rules differ from a theme script:

Add the code to a test group other than Control. Control cannot carry custom code.
Build any elements your script renders into inside the window.ABConvertQueue callback. Custom JavaScript runs before the page has a <body>.

Push the callback that builds the markup first; the queue runs callbacks in order.

Send assignments to another tool

Check the Integrations page in the ABConvert admin first. The Google Analytics 4 (GA4), Segment, and Heatmap integrations there send assignments with no theme code. Write this only for a tool that is not on that page, or for a tag manager that reads window.dataLayer. Every destination is the same loop: wait for ABConvert, then send one event per test. Send testGroup.index as the identifier, because you can rename a test group while the test runs.

window.ABConvertQueue = window.ABConvertQueue || [];
window.ABConvertQueue.push(function (ABConvert) {
  ABConvert.getAssignments()
    // Skip your own forced and preview visits. ABConvert leaves them out of
    // its own results, so sending them would skew the other tool's numbers.
    .filter(function (a) { return a.reason !== 'url_force_assign' && a.reason !== 'preview_override'; })
    .forEach(send);
});

Then write send for your destination:

// Google Tag Manager, or any tag that reads window.dataLayer. The event name
// and exp_variant_string format match what other testing tools push, so one
// trigger serves them all.
function send(assignment) {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'experience_impression',
    exp_variant_string: 'abconvert-' + assignment.experimentId + '-' + assignment.testGroup.index,
    experiment_name: assignment.experimentName,
    variant_name: assignment.testGroup.name,
  });
}

// Most session recording and heatmap tools take one call per test.
// yourTool: the tool's own SDK object.
function send(assignment) {
  yourTool.tagSession({
    experiment_id: assignment.experimentId,
    experiment_name: assignment.experimentName,
    variant_id: String(assignment.testGroup.index),
    variant_name: assignment.testGroup.name,
  });
}

The cookbook’s data platform example adds PostHog and Mixpanel destinations and sends each assignment once per session.

Render a custom price element

Product page detail: a card titled Add the wax kit lists Special ski wax at $62.70, written by the script, and Wax applicator at $6.00. — The bundle block, priced for this visitor's test group

ABConvert rewrites the price elements your theme renders on product and collection pages. A bundle block, promo block, or quick-view card you build yourself is not one of those, so it keeps showing the theme’s price. The bundle block in the screenshot is one of those. Mark the price of each product variant in it with class="custom-price" and the product variant’s ID. Leave the theme’s own price inside as the fallback for visitors who are not in the test:

<div class="bundle">
  <h3>Add the wax kit</h3>
  <div class="bundle__row">
    <span>Special ski wax</span>
    <span class="custom-price" data-variant-id="47522361606401">$57.00</span>
  </div>
  <div class="bundle__row">
    <span>Wax applicator</span>
    <span>$6.00</span>
  </div>
</div>

Then add this script to your theme layout. Every marked element shows the price the visitor’s test group gets:

window.ABConvertQueue = window.ABConvertQueue || [];
window.ABConvertQueue.push(function (ABConvert) {
  document.querySelectorAll('.custom-price[data-variant-id]').forEach(function (element) {
    const price = ABConvert.getPriceByVariantId?.(element.dataset.variantId);
    // null: the visitor is not in the test. Leave the theme's price alone.
    if (!price) return;
    const text = ABConvert.formatPrice(price.amount, price.currency);
    // Write only on change. ABConvert watches the page, and a rewrite of an
    // unchanged element would trigger it, then this script, in a loop.
    if (element.textContent !== text) element.textContent = text;
  });
});

The visitor in the screenshot is in Variant A, so the script replaced the fallback $57.00 with their test price of $62.70. A visitor outside the test keeps the $57.00 the theme rendered, because getPriceByVariantId returns null for them. This runs once per page load. The cookbook’s custom price example adds the compare-at price and a data-product-id form for “From $X” cards. It also re-runs when the page changes, so product variant switches, Ajax collection filters, cart drawers, and lazy-loaded cards get the right price.

Render a free shipping progress bar

A pale green bar above a mobile storefront header reading Spend $51.00 more for free shipping, with a progress track about a third full. — The gap to the visitor's own free shipping threshold

The bar needs two numbers: the threshold from ABConvert, and the cart subtotal from Shopify. Read the subtotal with Shopify’s Ajax API. GET /cart.js returns items_subtotal_price in cents, in the cart’s currency. Add the bar to your theme with a child element for the text, so the script never overwrites the progress track:

<div class="shipping-bar" hidden>
  <span class="shipping-bar__text"></span>
</div>

Then add this function. A visitor in the test sees “Spend $51.00 more for free shipping” until the subtotal reaches the threshold, then “You have free shipping”:

async function renderShippingBar(ABConvert) {
  const bar = document.querySelector('.shipping-bar');
  if (!bar) return;
  const threshold = ABConvert.getFreeShippingThreshold?.();   // on a multi-zone test, pass { zone }
  if (!threshold) {
    bar.hidden = true;   // not in a shipping test, or no free rate
    return;
  }

  const response = await fetch(window.Shopify.routes.root + 'cart.js');
  const cart = await response.json();
  if (cart.currency !== threshold.currency) {
    bar.hidden = true;   // cannot compare across currencies
    return;
  }
  const subtotal = cart.items_subtotal_price / 100;   // Shopify returns cents

  const remaining = Math.max(0, threshold.amount - subtotal);
  const text = remaining > 0
    ? 'Spend ' + ABConvert.formatPrice(remaining, threshold.currency) + ' more for free shipping'
    : 'You have free shipping';
  const target = bar.querySelector('.shipping-bar__text') || bar;
  if (target.textContent !== text) target.textContent = text;
  bar.hidden = false;
}

window.ABConvertQueue = window.ABConvertQueue || [];
window.ABConvertQueue.push(function (ABConvert) {
  // A failed cart read leaves the bar hidden.
  renderShippingBar(ABConvert).catch(function () {});
});

Re-run renderShippingBar when the cart changes. Shopify’s Storefront Events API dispatches shopify:cart:lines-update, which bubbles to document, when the visitor changes cart lines. The event fires when the update starts, so before you read the cart, wait for event.promise:

document.addEventListener('shopify:cart:lines-update', function (event) {
  event.promise.then(function () {
    if (window.ABConvert) renderShippingBar(window.ABConvert).catch(function () {});
  });
});

A theme that changes the cart with Shopify.actions.updateCart always fires that event. A theme that posts to /cart/add.js directly fires it only when the theme’s own code dispatches it. If your theme does not, call renderShippingBar from the theme’s own cart event instead. Dawn publishes cart-update through the subscribe helper in assets/pubsub.js. That helper exists only after the theme’s scripts have run, so subscribe inside your queue callback, not at the top of your script. The cookbook’s free shipping bar example handles both, and covers a theme that fires neither.

A dark rounded card across the bottom of a mobile storefront reading Your offer, 30% off, with a white Shop now button. — The visitor's offer, pinned to the bottom

Add the banner to your theme with a child element for the title, so the script leaves the label and the button alone:

<div class="offer-banner" hidden>
  <span class="offer-banner__label">Your offer</span>
  <span class="offer-banner__title"></span>
  <a class="offer-banner__cta" href="/collections/all">Shop now</a>
</div>

The script writes the title of the visitor’s first offer, “30% off” in the screenshot, and hides the banner when the visitor has no offer:

window.ABConvertQueue = window.ABConvertQueue || [];
window.ABConvertQueue.push(function (ABConvert) {
  const offer = (ABConvert.getOffers?.() || [])[0];   // getOffers is absent without an offer test
  const banner = document.querySelector('.offer-banner');
  if (!banner) return;
  if (!offer) {
    banner.hidden = true;
    return;
  }
  const title = banner.querySelector('.offer-banner__title') || banner;
  if (title.textContent !== offer.title) title.textContent = offer.title;
  banner.hidden = false;
});

The cookbook’s offer banner example reads the cart’s item count and adds “You save 10%. Add 2 more items to save 20%” for a volume discount.

​Send assignments to another tool

​Render a custom price element

​Render a free shipping progress bar

​Render an offer banner

Send assignments to another tool

Render a custom price element

Render a free shipping progress bar

Render an offer banner