Functions

Functions and properties available on the discountNinja.api namespace.

The documentation below describes the API as of version 9.x of the script.

Public properties or functions that are not in the discountNinja.api namespace should be considered obsolete and will be removed in the next major version release.

Using undocumented functions or objects will result in issues as custom code that relies on those functions or objects may break in the future when Discount Ninja's script is automatically updated.

Cache

Clear

Async	Yes
Function	await discountNinja.api.cache.clear()
	Clears all session and local storage data used by the script. Also clears the content of the indexedDb used by the script.
Type	Public
	This function is intended for use in troubleshooting sessions.

Syntax

//Clear cache
if (discountNinja) await discountNinja.api.cache.clear();

Cart

Add

Async	Yes
Function	await discountNinja.api.cart.add(variant: number, quantity: number, properties?: Record<string, string>, sellingPlanId?: number)
	Adds a variant to the cart. Note: this is an asynchronous function; the result must be awaited.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	variant (number): the variant id
	quantity (number): the number of items to add
	properties? (Record<string, string>): an optional object with key/value pairs of line item properties
	sellingPlanId? (number): an optional selling plan (to allow for recurring purchases based on a subscription)

Syntax

async function addVariantToCart() { 
    if (!discountNinja) return;
    
    const variant = 123456; //Ensure the variant id exists on the shop
    const quantity = 1;
    const properties = { "my_property": "my value", "my_property_2": "another value" };
    const sellingPlanId = 123456; //Ensure this is a valid selling plan for the variant
    
    //Add the variant
    await discountNinja.api.cart.add(variant, quantity);
    //Add the variant with a line item property
    await discountNinja.api.cart.add(variant, quantity, properties);
    //Add the variant with a selling plan
    await discountNinja.api.cart.add(variant, quantity, undefined, sellingPlanId);
}

//Run the above test
await addVariantToCart();

Content

Async	No
Property	discountNinja.api.cart.content
	Can be used to get access to an object that represents the content of the cart, including any discounts applied by Shopify's backend.
Type	Public
	This function is intended for use in integration code by third parties.
Return value	object | null Returns the Shopify cart object. Returns null if no cart is available.

Syntax

function logShopifyCart() {
    const cart = discountNinja discountNinja.api.cart.content ? null;
    const itemCount = cart ? cart.item_count : 0;
    console.log(`There are currently ${itemCount} items in the cart`, cart);
}

logShopifyCart()

Prefill

Async	Yes
Property	await discountNinja.api.cart.prefill(variants?: string[], redirectUrl?: string)
	Can be used to prefill a cart with specific variants. Typically used to create a link to a prefilled, discounted cart. Cf. https://support.discountninja.io/en/articles/5194395-how-to-build-a-prefilled-discounted-cart
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	variants?: string[]: a comma-separated list of the variant id of the product variants you want to add to the cart; for each variant you'll need to specify the quantity.
	This parameter is optional. If it is omitted, the app will look for a query parameter named variants instead. If neither is available the prefill method will not execute.
	redirectUrl?: string: define which page should be loaded once the cart is prefilled
	This parameter is optional. If it is omitted, the app will look for a query paramer named redirectUrl instead. If neither is available the default value is "/cart".

Syntax: example 1

This script can be used on a cart template to automatically prefill the cart based on the query parameters as explained here: ttps://support.discountninja.io/en/articles/5194395-how-to-build-a-prefilled-discounted-cart

<script type="text/javascript">
    document.addEventListener("la:dn:promotions:loaded", async function() { 
	if (discountNinja) await discountNinja.api.cart.prefill();
    });
</script>

Syntax: example 2

Alternatively, create a variants array manually and then

async function prefillCartWithSpecificVariants() {	
    // Replace 123456 and 2345678 with valid variant ids
    // Add a quantity of 1 of the variant with id 1234567x1
    // and a quantity of 2 of the variant with id 2345678x2
    // then, redirect to the home page
    const variants = [];
    variants.push('1234567x1');
    variants.push('2345678x2');
    if (discountNinja) await discountNinja.api.cart.prefill(variants, '/');
}

await prefillCartWithSpecificVariants();

Checkout

Is discounted

Async	Yes
Function	await discountNinja.api.checkout.isDiscounted()
	Can be used to check if any of the promotions apply to the cart and result in a product, order or shipping discount.
Type	Public
	This function is intended for use in integration code by third parties.
Return value	Promise<boolean> Returns a promise which resolves to a boolean. The return value indicates if the app will instruct Shopify to apply discounts at checkout. Additionally, when this function returns true, the script will attempt to take over the checkout process when the cart form is submitted using a checkout button.

Syntax

document.addEventListener("la:dn:cart:updated", async function(event) {
    const discountedCart = event.detail.data[0]; 
    const isDiscounted = await discountNinja.api.checkout.isDiscounted();
    if (isDiscounted) {                
        console.log('The cart is discounted', discountedCart);
        // Add logic when the cart is discounted by Discount Ninja offers
    }
    else {
        console.log('The cart is not discounted', discountedCart);
        // Add logic when the cart is not discounted by Discount Ninja offers
    }
});

Add pipeline rule

Async	No
Function	discountNinja.api.checkout.addPipelineRule()
	Can be used to add custom business logic that is executed when the customer click the checkout button.
	Discount Ninja needs to take over the checkout process when a user clicks the checkout button to ensure the checkout is correctly discounted.
	As a result, the app overrides any logic you may have associated with clicking the checkout button. To execute this logic you can add it to the pipeline of rules that is executed by the app.
	Each pipeline rule is a parameterless function that returns a boolean indicating if execution should continue (true) or not (false).
Type	Public
	This function is intended for use in integration code by third parties.
Return value	boolean The return value indicates if the rule was added properly.

Syntax

function checkoutPipelineRule1() {
    //Add your logic here
    //Return true to indicate that the customer can continue to the checkout
    //Return false to halt the pipeline
    console.log('Executing checkout pipeline rule 1');
    return true; 
}

function checkoutPipelineRule2() {
    //Add your logic here
    //Return true to indicate that the customer can continue to the checkout
    //Return false to halt the pipeline
    console.log('Executing checkout pipeline rule 2');
    return true; 
}

function registerCheckoutPipelineRules() {
    const successfullyAddedRule1 = 
        discountNinja.api.checkout.addPipelineRule(checkoutPipelineRule1);
    const successfullyAddedRule2 = 
        discountNinja.api.checkout.addPipelineRule(checkoutPipelineRule2);
    if (successfullyAddedRule1 && successfullyAddedRule2) {
        console.log('Pipeline rules successfully registered');
    }
    else {
        console.error('Pipeline rules could not be registered');
    }
}

//Check if the API is ready
if (typeof discountNinja === 'undefined' || 
    typeof discountNinja.api === 'undefined') {
    //The API is not ready, wait for it
    document.addEventListener("la:dn:api:ready", function(event) { 
        registerCheckoutPipelineRules();
    });
}
else {
    //The API was already available, no need to wait
    registerCheckoutPipelineRules();
}

Discount code

Add

Async	Yes
Function	await discountNinja.api.discountCode.add(discountCode: string)
	Adds a discount code or promotion code to the Discount Ninja promotion code field programmatically.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	discountCode (string): the discount code to add

Syntax

async function addDiscountCode(discountCode) {
    if (discountNinja) await discountNinja.api.discountCode.add(discountCode);
    console.log(`Added the promotion with promotion code '${discountCode}' to the cart`);
}

await addDiscountCode('WELCOME10');

Remove

Async	Yes
Function	await discountNinja.api.discountCode.remove(discountCode: string)
	Removes a discount code or promotion code from the Discount Ninja promotion code field programmatically.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	discountCode (string): the discount code to remove

Syntax

async function removeDiscountCode(discountCode ) {
    if (discountNinja) await discountNinja.api.discountCode.remove(discountCode);
    console.log(`Removed the promotion with promotion code '${discountCode}' from the cart`);
}

await removeDiscountCode('WELCOME10');

Discounted cart

Content

Property	discountNinja.api.discountedCart.content
	Can be used to get access to an object that represents the content of the cart, including any discounts applied by Shopify's backend.
Type	Internal
	This is an internal function or property. Use it only for debugging purposes. Do not rely on this function or property in your integration code.
Return value	object | null Returns an object representing the current cart, with the applicable Discount Ninja offers applied. Note that amounts returned are in cents, not in dollars.

Syntax

function logDiscountedCart() {
    const discountedCart = discountNinja ? discountNinja.api.discountedCart.content : null;
    console.log(`The discounted cart`, discountedCart);
}

logDiscountedCart()

Entitlements

Property	discountNinja.api.entitlements
	Lists the entitlements that apply based on the available offers. The array contains one item for each available offer. It details the prerequisites that were found in the cart, the discount amount, the target products and the entitled line items that were found in the cart.
Type	Public
	This function is intended for use in integration code by third parties..
Return value	object[] | null Returns an array of Entitement info objects.

Syntax

function logEntitlements() {
    if (discountNinja) console.log(`Entitlements`, discountNinja.api.entitlements);
}

logEntitlements()

Events

Subscribe

This function is not used to subscribe to events. Instead it is simply a helper function that prints sample code to the log console to explain how to subscribe to an event.

Async	No
Function	discountNinja.api.events.subscribe(eventName: string)
	Provides instructions on how to subscribe to an event with a given name. Note: this function does not, itself, subscribe to the event.
	See the list of available events.
Type	Public
	This function is intended for use in integration code by third parties.

Syntax

function printInstructionsToSubscribeToEvent(event) {
    if (discountNinja) discountNinja.api.events.subscribe(event);
}

printInstructionsToSubscribeToEvent('cart:updated')
// Prints the following message on the console:
// To subscribe to this event use the following code: 
// document.addEventListener("la:dn:cart:updated", function(event) { const eventData = event.detail.data[0]; console.log('Event la:dn:cart:updated was published.', eventData); });

Publish

Async	No
Function	discountNinja.api.events.publish(eventName: string)
	Publishes an event to the PriceRuleEngine.
	See the list of available events.
Type	Public
	This function is intended for use in integration code by third parties.

Syntax

function test() {
    if (discountNinja) discountNinja.api.events.publish('cart:updated');
}

Help

Async	No
Function	discountNinja.api.help()
	Prints a link to this page on the console.
Type	Public
	This function is intended for use in integration code by third parties.

Syntax

discountNinja.api.help()

Line item

Get updated key

Async	No
Function	discountNinja.api.lineItem.getUpdatedKey(key: string)
	Returns the updated key associated with a cart line item. A key can be updated by Shopify's back-end when properties are added, a selling plan changes or a discount is added. Cf. https://support.discountninja.io/en/articles/9109023-fix-network-requests-to-cart-js
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	key (string): the original key of the cart line item
Return value	string The updated key.

Syntax

function test() {
    for (let i = 0; i < cart.items.length; i++) {
        const item = cart.items[i];
        let key = item.key;
        if (discountNinja) {
            key = discountNinja.api.lineItem.getUpdatedKey(key);
        }
        
        // ... use the updated key, for example, to send requests to cart.js
    }
});

Offers

All

Async	No
Function	discountNinja.api.offers.all
	Lists all the active offers loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Return value	object[] An array of offer objects, representing the offers that are applicable in the current context.

Syntax

document.addEventListener("la:dn:promotions:loaded", function(event) { 
    const offers = discountNinja ? discountNinja.api.offers.all : null;
    console.log('Offers loaded', offers);
});

Get

This function is used to look up an offer that is available in the browser's cache. To load a promotion that is not available to the browser, use the Promotion Trigger function or the Discount Code Add function instead.

Async	No
Function	discountNinja.api.offers.get(token: string)
	Finds a specific offer in the list of all the active offers loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Parameters	token (string): the token of the offer to find
Return value	object | null Anoffer object if the offer is found, otherwise null.

Syntax

document.addEventListener("la:dn:promotions:loaded", function(event) { 
    const offerToken = 'ABCD';
    const bfcmOffer =  discountNinja ? discountNinja.api.offers.get(offerToken) : null;
    if (bfcmOffer === null) {
        console.log(`Offer with token ${offerToken} not found`);
    }
    else {
        console.log(`Offer with token ${offerToken} found`, bfcmOffer);
    }
});

Promotions

All

Function	discountNinja.api.promotions.all
	Lists all the active promotions loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Return value	object[] An array of promotion objects, representing the promotions that are applicable in the current context. The promotion object provides information about the trigger used and the list of offers associated with the promotion.

Syntax

document.addEventListener("la:dn:promotions:loaded", function(event) { 
    const promotions = discountNinja ? discountNinja.api.promotions.all : null;
    console.log('Offers loaded', promotions);
});

Get

This function is used to look up a promotion that is available in the browser's cache. To load a promotion that is not available to the browser, use the Promotion Trigger function or the Discount Code Add function instead.

Function	discountNinja.api.promotions.get(token: string)
	Finds a specific promotion in the list of all the active promotions loaded by the app.
Type	Internal
	This function returns an internal object. Do not rely on the properties of this object in your integration code as they may be removed or renamed in future versions.
Parameters	token (string): the token of the promotion to find
Return value	object | null A promotion object if the promotion is found, otherwise null.

Syntax

document.addEventListener("la:dn:promotions:loaded", function(event) { 
    const promotionToken = 'ABCD';
    const bfcmPromotion = discountNinja ? discountNinja.api.promotions.get(promotionToken) : null;
    if (bfcmPromotion === null) {
        console.log(`Promotion with token ${promotionToken} not found`);
    }
    else {
        console.log(`Promotion with token ${promotionToken} found`, bfcmPromotion);
    }
});

Trigger

Async	No
Function	discountNinja.api.promotions.trigger(tokens: string)
	Triggers a private promotion programmatically.
	Use this as a programmatic alternative to using a discount link. To trigger a promotion based on a promotion code, use the Discount Code Add function instead.
Type	Public
	This function is intended for use in integration code by third parties.
Parameters	tokens (string | string[]): the token(s) of the promotion(s) to trigger

Syntax

function triggerCustomPromotion() {
    const bcfmPromotionToken = 'ABCD';
    if (discountNinja) discountNinja.api.promotions.trigger(bcfmPromotionToken);
}

<a href='javascript:triggerCustomPromotion()'>Unlock the BFCM promo!</a>
<button onclick='triggerCustomPromotion()'>Unlock the Cyber Monday offer!</button>

Strikethrough Pricing

Apply

Async	Yes
Function	await discountNinja.api.strikethroughPricing.apply()
	Triggers a refresh of all strikethrough pricing programmatically. This is typically not required since the app automatically detects situations where the strikethrough pricing must be updated.
	For an event based approach, use this event instead.
Type	Public
	This function is intended for use in integration code by third parties.

Syntax

async function myPriceUpdateLogic() {
    //Trigger Discount Ninja's strikethrough pricing rendering
    if (discountNinja) await discountNinja.api.strikethroughPricing.apply();
};