Integration

Discount Ninja includes out-of-the-box integration with a variety of apps and Shopify features.

Subscription apps

• The app automatically detects subscription products and can handle a checkout where one-time purchases and subscription products are combined.

• The app was tested with:

  • Shopify's subscription app

  • Seal

  • Appstle

  • Recharge

  • Yotpo

  • Stay.ai

• Some subscription apps provide a table or box on product pages (PDP) that presents the one-time-purchase and subscription prices. If you need to display discounted prices for the one-time-purchase and subscription prices, you'll need to make some code edits. Learn more about this use case here.

Email marketing apps

Trigger a promotion from an email

You can trigger a promotion using a discount link. The discount link is essentially a link to a landing page followed by the token of the promotion. The app includes a handy tool to build those links. A discount link automatically triggers the promotion for the customer and navigates to the landing page you have selected.

Most email marketing tools allow you to add a link to a word or a button through their user interface. If you need to manually add them using HTML, here are some examples that can get you started:

• include a simple link

Activate your discount now, by clicking <a href="https://YOUR-SHOP-URL-HERE/?token=ABCD">here</a>.

• include a button

<div style="display:flex;align-items:center;justify-content:center;text-align:center;margin:20px;max-width:200px;height:50px;background:#000;border:2px solid #fff;border-radius:6px;">
    <a href="https://YOUR-SHOP-URL-HERE/?token=ABCD" style="color:#fff;text-decoration:none;">
        SHOP&nbsp;THE&nbsp;DEAL
    </a>
</div>

Note that https://YOUR-SHOP-URL-HERE/?token=ABCD must be replaced by the discount link of the promotion you want to trigger. For example: https://www.mystore.com/?token=EY1UM

Discount code wrapper

Discount Ninja can also detect discount codes generated by email marketing apps, more specifically:

• Klaviyo: Email marketing

Loyalty apps

• Discount codes generated by loyalty apps can be redeemed using Discount Ninja's promotion code field.

• The app includes an offer type to build "wrapper" promotions to display Discount Ninja widgets when a loyalty discount code is entered in the promotion code field.

• Discount Ninja can detect discount codes generated by the following apps:

  • Appstle Loyalty & Rewards

  • Influenci.io: Loyalty Rewards

  • Loyalty & referrals by Yotpo (Swell)

  • Loyalty, rewards and referrals by LoyaltyLion

  • Loyalty, Wishlist, Reviews UGC by Growave

  • Referral Candy

  • Smile: Rewards & Loyalty

  • Stamped.io Loyalty & Rewards

Pickup + delivery apps

• Discount Ninja has built in integration with Zapiet.

  The integration relies on a method named Zapiet.Widget.checkoutEnabled() which must evaluate to true to allow the app to continue the checkout pipeline.

Prefill checkout information

• Discount Ninja requires that third party developers add query parameters to the action attribute of the cart form, which is a standard technique to pass information from the cart to the checkout.

• To prefill shipping information at checkout based on a selection made in the checkout, third party developers must ensure the action attribute of the cart form included the correct query parameters. This can be done using JavaScript.

• Shopify provides a number of query parameters to prefill the checkout: https://shopify.dev/docs/apps/build/checkout/cart-permalinks/create-cart-permalinks

• Example of an action attribute, rendered by Liquid and updated by JavaScript:

<form action="/cart?checkout[shipping_address][city]=London" method="POST">
    ...
</form>

Currency conversion switchers

• The app detects the currency based on the Shopify.currency object

• We are compatible with all apps that rely on this object

Installment apps

• The app can apply discounts to installment payments proposed by:

  • AfterPay

  • QuadPay

  • Sezzle

  • Hoolah

  • ShopPay

Search and filter apps

• Rendering discounted prices in search results and collections managed by apps requires the following:

  • Discount Ninja must be able to identify where prices are rendered. This can be achieved in one of two ways:

    • Using a CSS selector

    • By marking the section with an attribute

  • For each collection product the app must, at a minimum, have access to the product handle

• The app has been tested with the following apps:

  • Boost AI Search & Filter (formerly known as PFS)

  • Searchanise Search & Filter

  • Globo Smart Search & Product Filter (SPF)

  • AI Search & Product Filter (Ultimate Search)

• For information on how to configure these apps to show strikethrough pricing, please refer to this page.

Page builders

• The app has different levels of support for different page builders. More information about each integration is available from the following support articles:

  • PageFly

  • Zipify Pages

  • GemPages

  • Shogun

Terms and conditions checkboxes

Behavior

The app automatically checks for known checkboxes that are related to terms and conditions. The app will not proceed the checkout pipeline until those checkboxes (if marked mandatory and visible) are checked.

Important: note that the logic to cancel the checkout based on the status of the checkbox should be present in the code of your theme (or the app that handles this checkbox). Discount Ninja does not display an error message, it relies on the theme to cancel the checkout and display a message.

Explicitly marking a checkbox

If you use a custom checkbox that isn't automatically detected by the app, you may need to mark it explicitly. To explicitly mark a checkbox as required before checkout, add the following attribute to the input field:

la-dn-checkout-required-checkbox

Syntax

<input 
    type="checkbox" 
    name="termsAndConditions" 
    form="cart" 
    la-dn-checkout-required-checkbox>
<label for="termsAndConditions">I accept the terms and conditions</label>

Markets

• The app can be used on stores that have multiple markets configured.

• Shopify functions mode supports most features included in Shopify Markets:

  • International pricing: fixed product prices configured in Shopify Markets are used.

  • Exchange rates: exchange rates will be applied to product prices as configured in Shopify Markets.

  • Rounding: rounding will be applied to product prices as configured in Shopify Markets.

• Caveats

  • Thresholds and fixed amounts: thresholds and fixed amount discounts are calculated based on the conversion rate defined in Shopify Markets.

  • Rounding: discounted prices are only rounded at checkout, not in the cart.

Other discount apps

• Discount Ninja strives to be as compatible as technically possible with other discount apps.

• Note that the app is not compatible with:

  • Shopify's automatic discounts

  • Apps that use a discounted checkout prepared by the Draft Order API

  • Apps that require more than two discount functions

  • Apps that add/remove products at checkout using Checkout UI extensions

Custom checkout logic

To integrate with custom checkout logic, you can :

• add a checkout pipeline rule (as documented here); this is typically a good solution if you wish to execute a validation rule before proceeding to the checkout

• use an event to trigger the checkout (as documented here); this is typically a good solution if you wish to take control of the checkout is some situations and leave Discount Ninja in control for other situations

Note: if your code redirects to the checkout by setting window.location you may want to leverage the above mentioned event as documented in the code snippet here.

Show/hide custom HTML

Discount Ninja includes building blocks that can display specific HTML content to help you promote offers.

If you need to show or hide custom HTML blocks, you can use the following classes:

• limoniapps-discountninja-whenproductdiscounted-show and limoniapps-discountninja-whenproductdiscounted-hide: these classes can be used on product pages only; they hide or show the content of the element based on whether the selected variant is discounted by Discount Ninja or not

• limoniapps-discountninja-whenactivepromotions-show and limoniapps-discountninja-whenactivepromotions-hide: hide or show the content of the element based on whether Discount Ninja active promotions are available for the visitor or not

• limoniapps-discountninja-whenpromotionsincart-show and limoniapps-discountninja-whenpromotionsincart-hide: hide or show the content of the element based on whether Discount Ninja promotions have been applied to the cart or not

• limoniapps-discountninja-whencartdiscounted-show and limoniapps-discountninja-whencartdscounted-hide: hide or show the content of the element based on whether the total amount of the cart is discounted by Discount Ninja promotions or not

Google Tag Manager Data Layer

To integrate with Google's data layer you may need to leverage the discounted price calculated by the app. The app publishes this information using an event. The following code provides an example of how you may use the data returned by that event:

// Subscribe to the event
document.addEventListener("la:dn:product:discount:calculated", function(event) {
    // Retrieve the data about the product after discounts have been calculated
    const productVariantPriceInfo = event.detail.data[0];
    const discountedPrice = productVariantPriceInfo.discountedPrice;  
    console.log('Discounted price is ' + discountedPrice, productVariantPriceInfo);
    
    // Your code to integrate with the data layer goes here
    // ...
});

Drawer cart split line items

When your cart contains multiple items of the same product variant, Shopify will split those items into multiple rows in the cart (and drawer cart) when:

• Line item property: One of the items has a different line item property (for example: 1 item has Color 'blue', the other item has a different value for 'Color' or does not specify a value for this property)

• Selling plan: One of the items is sold using a selling plan (subscription) and the other is not

• Discount: One of the items has a server-side discount associated with and the other does not

Discount Ninja applies hidden line item properties to BOGO and GWP products. This causes Shopify to split those lines.

To be able to change the quantity for each of those split lines individually, it is important that your theme updates quantity based on the key of the line item. The key of a line item is unique (also for split lines). If you update quantities based on the variant then Shopify will update the quantity of all lines that contain that variant, which leads to unexpected results.

See Shopify's documentation for more details:

Cart API referenceShopify

Cart.js API /cart/change.js

Drawer cart

Discount Ninja applies discounts using Shopify Functions. Most (if not all) themes have built-in support for visualizing the discounts applied in this way. However, they require that the page is reloaded to render those discounts. This causes a broken user experience for the customer when the cart or drawer cart is refreshed using JavaScript instead of reloading the page.

To ensure the drawer cart immediately reflects the discounts, you'll need to:

• Enable strikethrough pricing as documented here

• If you wish to re-render the drawer cart after Discount Ninja has applied the discount to the cart, subscribe to this event to be notified when the discount is applied.

Also check the following:

• Ensure you hide the native discount labels rendered by your theme using the limoniapps-discountninja-whenpromotionsincart-hide css class, as outlined here

• Ensure your theme updates the quantity of line items based on the line item key (as opposed to the variant)

• If your theme re-renders the drawer cart after it is opened, you need to instruct Discount Ninja to re-apply strikethrough pricing and re-render cart text and other widgets that may have been overwritten. Please refer to this event to implement this.

For the best customer experience, you'll also want to avoid that DN reloads the page when a gift is added/removed or a line is split (BOGO). To avoid reloading the page, configure DN to execute a line of JavaScript instead. This line should refresh the content of the drawer cart by fetching the content of the cart from Shopify and redrawing the drawer cart. This line is configured in the app under the Settings menu > General > Advanced > Refresh behavior

Refresh behavior JavaScript method

Progress bar

If your theme includes a progress bar that indicates how close a visitor is to unlocking a goal (e.g. free shipping), you may find that the progress bar isn't using the discounted total of the cart.

Discount Ninja applies discounts using Shopify Functions which ensures Shopify understands what the discounted total is. However, your theme's progress bar is not aware that discounts are applied immediately. This results in the progress bar showing incorrect data until the visitor reloads the page.

To avoid this, you'll need to programmatically update the progress bar whenever discounts are applied. This can easily be achieved with the Cart updated event.

Example:

document.addEventListener("la:dn:cart:updated", function(event) {
    const discountedCart = event.detail.data[0]; 
        
    //The code below simply adds a line in the console log    
    console.log('Ready to update the progress bar based on the discounted total', discountedCart.total.discountedPrice); 

    //Run a sample implementation for a shipping bar
    updateFreeShippingBar(discountedCart.total.discountedPrice);
});

function updateFreeShippingBar(discountedTotal) {
    //In this example we assume that the threshold is $50
    //We multiply by 100 to express the threshold in cents as opposed to dollars.
    //This allows us to compare the threshold to the discounted total.
    //We then multiply by the currency conversion rate provided by Shopify,
    //this allows us to handle multiple currencies.
    const conversionRate = Shopify.currency.rate;
    const freeShippingThresholdInCents = 50 * 100 * conversionRate;    
    
    //We can now calculate the amount remaining (i.e. how much more the visitor must
    //spend to reach the threshold). Note that the discountedTotal is provided
    //in cents and in the currently select currency.
    const centsRemaining = freeShippingThresholdInCents - discountedTotal; 
    
    //Finally, we can calculate this amount as a percentage of the total.
    const percentageRemaining = Math.max(centsRemaining, 0) / freeShippingThresholdInCents * 100;
    const percentageComplete = 100 - percentageRemaining;
     
    //TODO: Update the progress bar
    //You'll need to update the code below to update the progress bar 
    //based on the discounted total.
    //How that is accomplished depends on the specific theme you use. 
    console.log(`Free shipping is ${percentageComplete}% complete, ${percentageRemaining}% left`);
}

Order bump

An order bump is an upsell that can be added to the cart with a simple checkbox. Examples include:

• Shipping protection

• Gift wrapping

• Priority processing

Unfortunately order bumps are often implemented in a way that is not compatible with Discount Ninja. Specifically, the code that checks for the order bump is executed when the submit button of the cart is clicked and the code typically redirects to the checkout by setting window.location.

This technique is not compatible with DN. Read more about how to integrate this approach properly here.

Custom variant apps / swatch apps

Discount Ninja automatically detects when a variant is selected on the PDP (product page). The app automatically detects this in one of the following two ways:

• The selected variant is set in the query parameter using the variant query parameter. Example: https://my-shop.com/products/my-product?variant=123456

• The selected variant is set as the selectedOption of the select input control with its name attribute set to id.

If your PDP is not compatible:

• Change the code of your variant selector to allow the app to detect the change in one of the two aforementioned ways

• Or inform the app that a new variant has been selected using a variant changed event.

Example of using the variant changed event:

function myVariantChangedEventHandler() {
    // This function represents the function that handles the event
    // when your custom solution or swatch app has detected a new
    // variant has been selected.
    const variantId = 123456;
    
    // Discount Ninja integration code
    document.dispatchEvent(new CustomEvent('la:dn:variant:changed'), [variantId]);
}

Pagination on the PLP

To handle Infinite scrolling and Load more pagination you'll need to either implement an event or mark the button. See this page for more details.

Add to Cart Button

Discount Ninja does not integrate with the Add to Cart button specifically, nor does the app need themes or developers to make changes to those buttons for the app to work correctly.

Problem: multiple items added to cart

However, occasionally issues will occur where an Add to Cart button will appear to malfunction when Discount Ninja is installed. Specifically, in rare occasions, users may find that their Add to Cart button adds multiple instances of a product when clicked once.

Why this happens

This can happen when the theme's code contains a bug where clicking the Add to Cart results in two simultaneous network requests (to /cart.add.js). Shopify cannot process multiple simultaneous requests and, as a result, drops one of the requests and only honours one. This results in the expected behavior for the customer: only one item is added to the cart.

Discount Ninja forces network requests to be handled sequentially. This avoids situations where Shopify's inability to process simultaneous requests results in unexpected failures. This mechanism is important to ensure the functionality of the app works reliably.

As a result of processing the network requests sequentially, themes that accidentally send multiple simultaneous requests when the Add to Cart button is clicked, see a different behavior after installing Discount Ninja: the requests are now both honoured by Shopify, which results in multiple products being added to cart (2x the expected amount).

How to solve this

To resolve this, the user must fix the bug in the theme's code. This typically involves:

• ensuring the click/submit events are not subscribed to multiple times

• ensuring the click event of the button is not bubbled up to the form