Developer reference

Breakly storefront events and their event.detail fields, theme hooks, CSS classes, --bk custom properties, and how the Shopify Functions discount applies.

This page is for developers who connect Breakly's widget to a theme, a tracking script or another app.

Storefront events#

The widget dispatches two DOM events. Both are CustomEvents that bubble from the widget's root element (.breakly), so you can listen on document.

A click on add to cart and the form submit it causes fire breakly:add once.

event.detail#

Both events carry the same detail object:

Amounts are integer cents: total / 100 is the amount in the currency's main unit. The saving is regular - total.

document.addEventListener("breakly:tier-change", (event) => {
  const { quantity, total, regular, currency } = event.detail;
  console.log(quantity, (regular - total) / 100, currency);
});

document.addEventListener("breakly:add", (event) => {
  const { quantity, total, currency } = event.detail;
  // Send an add-to-cart event to your analytics tool.
});

The events are informational. Calling preventDefault() doesn't stop the add.

Theme hooks#

Two data attributes let you point Breakly at your theme's own elements. Put them inside the product's section, the element with the shopify-section class.

<div class="product__price" data-breakly-price>
  {{ product.selected_or_first_available_variant.price | money }}
</div>

<div class="custom-variant-picker" data-breakly-variants>
  …
</div>

For the price:

• Breakly writes the tier price into the first visible element that matches. Put the attribute on the element that holds the price text, or on a wrapper with a single child.
• An element with other child elements is skipped.
• Elements inside s or del, such as compare-at prices, are skipped.
• Breakly also recognizes common markup, including Dawn's and Horizon's price elements, so you need the attribute only when your theme isn't recognized.

CSS classes and custom properties#

You can style the widget with Custom CSS in Design. Breakly scopes every selector to .breakly. See Custom CSS for what it removes.

Root element#

The root element is div.breakly. It carries these attributes and modifier classes:

To target a modifier, write it on the root: .breakly.breakly--p-soft .breakly__tier. Custom CSS keeps selectors that start with .breakly as written.

Elements#

A tier waiting for a currency conversion has the data-pending attribute.

Custom properties#

.breakly { --bk-gap: .5em; --bk-border-w: 2px; }
.breakly__tier.is-selected .breakly__title {
  text-decoration: underline;
}

Design settings write some of these properties on the widget's style attribute: the accent, the corner radius, the title weight, any size other than Default and every element color you set. With automatic accent and corners, the widget's script also sets --bk-accent, --bk-on-accent and --bk-radius there. A custom CSS value only wins over those with !important. Prefer the Design settings for them.

Classes outside the widget#

Breakly adds these classes to your theme's elements. Custom CSS can't reach them, because it is scoped to the widget, but your theme's CSS can.

How the discount is applied at checkout#

Breakly applies its tiers with a Shopify Function, a product discount that runs in Shopify's cart and checkout.

• The store has one automatic app discount, titled Breakly quantity breaks. It covers every offer.
• The function reads each product's offer and counts the cart's items by product, by variant, or across the offer for mix and match.
• The discount on each cart line shows the tier's checkout message as its title.
• The widget and the function use the same integer-cent formula. Breakly tests both against the same price vectors, so the price on the product page is the price at checkout.
• Gift cards are never discounted. Subscription lines and B2B buyers are left out when the offer excludes them.
• For schedules, the function uses your store's local date and Breakly's list of offers running now, which Breakly refreshes every minute. For countries, it uses the buyer's country at checkout.
• In other currencies, it converts amounts set in your store currency with Shopify's presentment currency rate.

How each discount type reaches the cart:

Combinations#

The Breakly discount is created to combine with product discounts and shipping discounts, and with order discounts when Shopify allows it. If Shopify refuses the order combination, Breakly creates the discount without it.

On each item, Shopify applies only the better product discount for the customer. A product discount code or another app's product discount on the same item doesn't add up with a Breakly tier.

Discounts page#

In your Shopify admin, Create discount with Breakly opens a new offer in Breakly. Opening the Breakly discount from Discounts opens Breakly's Offers page.