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
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() { 
    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.api.cart.content;
    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() { 
	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');
    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) {
    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 ) {
    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.api.discountedCart.content;
    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() {
    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) {
    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() {
    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.api.offers.all;
    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.api.offers.get(offerToken);
    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.api.promotions.all;
    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.api.promotions.get(promotionToken);
    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';
    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.

Type

Public

This function is intended for use in integration code by third parties.

Syntax

async function myPriceUpdateLogic() {
    //Code that overwrites Discount Ninja's strikethrough pricing
    await discountNinja.api.strikethroughPricing.apply();
};
PreviousJavaScript APINextEvents

Last updated